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
- « Module not found: Can't resolve 'recharts' »
- « useTheme must be used within a ThemeProvider »
- La page affiche « Loading WakaUI... »
- Les fichiers de traduction sont téléchargés à chaque rendu
- Le mode sombre ne change rien
- Le thème de l'organisation s'affiche gris ou sans couleur
- Le thème de l'organisation disparaît au rechargement
- Un texte affiche sa clé, par exemple
common.buttons.save - Un libellé est vide
- Aucune notification ne s'affiche
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 :
@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.
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.
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 :
@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).
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), 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, 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.