Skip to content

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.

TroubleshootingDeveloper

This page has not been translated yet and is shown in French.

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

Symptômes

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.

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 :

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).

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.