# Résoudre les problèmes de waka-ui

> Composants sans style, dépendance introuvable, thème ou mode sombre sans effet, clés de traduction affichées - causes et solutions.

Cette page couvre les problèmes rencontrés en installant waka-ui, en appliquant un thème ou en traduisant l'interface.

## Symptômes

- [Les composants s'affichent sans couleur, sans bordure ou avec un fond transparent](#composants-sans-couleur-ni-bordure)
- [« Module not found: Can't resolve 'recharts' »](#dépendance-introuvable)
- [« useTheme must be used within a ThemeProvider »](#hook-hors-du-fournisseur)
- [La page affiche « Loading WakaUI... »](#loading-wakaui)
- [Les fichiers de traduction sont téléchargés à chaque rendu](#traductions-rechargées-en-boucle)
- [Le mode sombre ne change rien](#mode-sombre-sans-effet)
- [Le thème de l'organisation s'affiche gris ou sans couleur](#thème-sans-couleur)
- [Le thème de l'organisation disparaît au rechargement](#thème-non-conservé)
- [Un texte affiche sa clé, par exemple `common.buttons.save`](#clé-affichée-à-la-place-du-texte)
- [Un libellé est vide](#libellé-vide)
- [Aucune notification ne s'affiche](#notification-invisible)

## Composants sans couleur ni bordure

**Cause** : Tailwind CSS n'a pas généré les classes utilisées par les composants. Tailwind n'analyse pas `node_modules` : sans déclaration, les classes `bg-popover`, `border-input` ou `bg-primary` des composants de waka-ui n'existent pas dans votre feuille de style. Les listes déroulantes, menus et fenêtres sont les premiers touchés.

**Solution** : en Tailwind CSS 4, ajoutez dans votre CSS global, après l'import des styles de waka-ui :

```css
@source "../node_modules/@wakastellar/ui/dist";
```

Le chemin est relatif au fichier CSS. En Tailwind CSS 3.4, ajoutez `./node_modules/@wakastellar/ui/dist/**/*.js` au tableau `content` de `tailwind.config.js`. Redémarrez ensuite le serveur de développement.

## Dépendance introuvable

**Cause** : le point d'entrée principal de `@wakastellar/ui` contient des composants qui importent `recharts` et `react-hook-form`. Ces paquets ne sont pas installés automatiquement. Le même message apparaît avec `@tiptap/react`, `platejs`, `exceljs` ou `react-markdown` quand vous importez un point d'entrée dédié sans sa dépendance.

**Solution** : installez la dépendance nommée dans le message, par exemple `npm install recharts@^2 react-hook-form`. La liste par point d'entrée est dans [Composants et blocks](/v1.0/interface-waka-ui/composants-et-blocks#points-dentrée-dédiés).

## Hook hors du fournisseur

**Cause** : `useTheme`, `useLanguage`, `useWaka`, `ThemeSelector` ou un composant qui les utilise est rendu en dehors de `WakaProvider`. Le message est « useTheme must be used within a ThemeProvider » ou « useLanguage must be used within a LanguageProvider ».

**Solution** : vérifiez que le composant est placé sous `WakaProvider`, par exemple dans un layout enveloppé par votre composant `Providers`.

## Loading WakaUI

**Cause** : `WakaProvider` affiche « Loading WakaUI... » tant qu'il initialise ses traductions dans le navigateur. C'est normal pendant un court instant à l'ouverture de la page, et le contenu placé sous lui n'apparaît pas dans le HTML rendu par le serveur.

**Solution** : si le texte reste affiché, ouvrez la console du navigateur et cherchez un message commençant par `[WakaUI]`. Pour une page publique qui doit être rendue côté serveur, placez `WakaProvider` dans le layout de la zone connectée seulement.

## Traductions rechargées en boucle

**Cause** : la propriété `config` de `WakaProvider` est un nouvel objet à chaque rendu, par exemple écrite directement dans le JSX. Chaque nouvel objet réinitialise les traductions, et relance leur téléchargement si vous utilisez `language.s3Config`.

**Solution** : déclarez la configuration hors du composant, ou construisez-la avec `useMemo`, comme dans [Traduire l'interface](/v1.0/interface-waka-ui/traduire-l-interface).

## Mode sombre sans effet

**Cause possible 1** : `theme.enableSystem` n'est pas à `true`. Sans ce réglage, `toggleDarkMode` ne fait rien.

**Cause possible 2** : en Tailwind CSS 4, les classes `dark:` suivent par défaut le réglage du système, pas la classe `dark` que pose waka-ui.

**Solution** : passez `enableSystem: true` dans la configuration, et ajoutez dans votre CSS global :

```css
@custom-variant dark (&:where(.dark, .dark *));
```

## Thème sans couleur

**Cause** : les couleurs du thème ne sont pas écrites en composantes HSL. waka-ui compose `hsl(var(--primary))` : une valeur `oklch(0.55 0.19 150)`, `hsl(221 83% 53%)` ou `#2563eb` produit une couleur invalide, que le navigateur ignore.

**Pour vérifier** : dans l'inspecteur, sélectionnez l'élément `<html>` et regardez la valeur de `--primary` : elle doit ressembler à `221.2 83.2% 53.3%`.

**Solution** : créez un nouveau thème Wakastart avec des couleurs dans ce format et désignez-le à la place de l'ancien (voir [Créer un thème CSS](/v1.0/apparence/creer-un-theme-css)).

## Thème non conservé

**Cause** : l'identifiant du thème n'est pas déclaré dans `theme.themes`. Au chargement, waka-ui ignore un thème mémorisé qui ne figure pas dans la liste et revient à `defaultTheme`.

**Solution** : ajoutez `{ id: "organisation", label: "Thème de l'organisation" }` à `theme.themes`, avec le même identifiant que celui passé à `changeTheme`.

## Clé affichée à la place du texte

**Cause possible 1** : la clé n'existe ni dans la langue affichée ni dans la langue par défaut de vos traductions.

**Cause possible 2** : la langue n'est pas dans `supportedLanguages`, ou ses traductions ne sont pas passées dans `resources`.

**Solution** : vérifiez la clé dans les traductions `FRONT` de votre application (voir [Langues et traductions](/v1.0/langues-et-traductions)), puis la configuration `language` de `WakaProvider`.

## Libellé vide

**Cause** : la clé existe dans le fichier de traduction avec une valeur vide. Wakastart publie une clé sans traduction sous la forme d'une chaîne vide, et i18next l'affiche telle quelle.

**Solution** : retirez les valeurs vides avant de passer les traductions à `WakaProvider`, comme la fonction `dropEmptyValues` de [Traduire l'interface](/v1.0/interface-waka-ui/traduire-l-interface), ou renseignez la traduction manquante.

## Notification invisible

**Cause** : aucun `<Toaster />` n'est rendu dans la page. `useToast` ajoute la notification, mais rien ne l'affiche.

**Solution** : rendez `<Toaster />` une fois, dans votre composant `Providers`.
