Référence de waka-ui
Paquet, versions, prérequis, points d'entrée, configuration de WakaProvider, hooks, variables de couleur et ligne de commande de waka-ui.
Cette page rassemble les valeurs de référence de waka-ui. Le détail de chaque composant se consulte sur ui.wakastart.app.
Paquet
| Élément | Valeur |
|---|---|
| Nom | @wakastellar/ui |
| Registre | registre npm public, sans authentification |
| Dernière version au 2 novembre 2026 | 6.1.4 |
| Versions publiées | npmjs.com/package/@wakastellar/ui |
| Formats | ES modules et CommonJS, types TypeScript inclus |
Les numéros de version suivent le versionnage sémantique : une version majeure signale un changement incompatible, par exemple une dépendance dont la plage acceptée se resserre. Épinglez une version exacte dans votre package.json et montez de version volontairement, après avoir vérifié vos écrans.
Prérequis
| Dépendance | Version acceptée | Obligatoire |
|---|---|---|
next | 14 ou plus (testé sur 16) | oui |
react, react-dom | 18 ou plus (testé sur 19) | oui |
tailwindcss | 3.4 ou plus, ou 4 | oui |
recharts | 2.x | oui pour le point d'entrée principal et /charts |
react-hook-form | 7.x | oui pour le point d'entrée principal |
| Node.js | 22 ou plus | — |
Les dépendances des éditeurs et de l'export sont listées dans Composants et blocks.
Points d'entrée
| Import | Contenu |
|---|---|
@wakastellar/ui | composants, blocks, fournisseurs, hooks, types |
@wakastellar/ui/components/<dossier> | un composant seul, par exemple components/button |
@wakastellar/ui/blocks/<dossier> | un block seul, par exemple blocks/error-pages |
@wakastellar/ui/hooks/use-toast, @wakastellar/ui/hooks/use-translation | un hook seul |
@wakastellar/ui/charts | graphiques |
@wakastellar/ui/rich-text | éditeur de texte riche |
@wakastellar/ui/export | export et import des tableaux |
@wakastellar/ui/doc | rendu de documentation |
@wakastellar/ui/editor | éditeur de blocs (Plate) |
@wakastellar/ui/md-editor | éditeur Markdown |
Feuilles de style
| Import | Usage |
|---|---|
@wakastellar/ui/styles | Tailwind CSS 4 : Tailwind, variables et thèmes intégrés |
@wakastellar/ui/styles/v4 | identique à styles |
@wakastellar/ui/styles/v3 | Tailwind CSS 3.4 |
@wakastellar/ui/styles/base | variables et thèmes seuls, sans Tailwind |
@wakastellar/ui/tailwind-preset | preset de configuration pour Tailwind CSS 3.4 |
Tailwind CSS 3
Pour un projet en Tailwind CSS 3.4, remplacez l'étape « Importer les styles » de l'installation par les deux réglages suivants.
-
Dans
tailwind.config.js, ajoutez le preset et les composants compilés de waka-ui :JavaScriptmodule.exports = { presets: [require("@wakastellar/ui/tailwind-preset")], content: [ "./app/**/*.{js,ts,jsx,tsx}", "./components/**/*.{js,ts,jsx,tsx}", "./node_modules/@wakastellar/ui/dist/**/*.js", ], };Le preset déclare les couleurs du thème et le mode sombre par classe.
-
Dans
app/layout.tsx, importez la feuille de style :TSXimport "@wakastellar/ui/styles/v3";
Configuration de WakaProvider
WakaProvider reçoit une propriété config de type WakaProviderConfig. Gardez-la stable d'un rendu à l'autre : une nouvelle configuration réinitialise les traductions.
language
| Champ | Type | Défaut | Description |
|---|---|---|---|
defaultLanguage | chaîne | obligatoire | langue au premier affichage, et langue de repli d'une clé absente |
supportedLanguages | tableau de chaînes | obligatoire | codes des langues acceptées, par exemple ["fr", "en"] |
languages | tableau de { code, label, flagEmoji?, flag? } | [] | langues affichées par LanguageSelector et renvoyées par useWaka().languages |
resources | objet | — | traductions de l'application, sous la forme { fr: { translation: { … } } } |
s3Config | { bucketUrl, translationsPath? } | — | chargement des traductions par URL : <bucketUrl>/<translationsPath>/<langue>.json, sans en-tête d'authentification. translationsPath vaut translations par défaut |
storageKey | chaîne | waka-ui-language | clé de mémorisation de la langue dans le navigateur |
theme
| Champ | Type | Défaut | Description |
|---|---|---|---|
defaultTheme | chaîne | default | identifiant du thème au premier affichage |
themes | tableau de { id, label, description?, previewColor? } | [{ id: "default", label: "Default" }] | thèmes proposés par ThemeSelector ; un thème mémorisé qui n'y figure pas est ignoré |
enableSystem | booléen | false | active le mode sombre : mode du système à la première visite, puis choix mémorisé |
s3Config | { baseUrl, prefix?, extension?, headers?, timeout? } | — | chargement des thèmes par URL : <baseUrl>/<prefix>/<id>.<extension>. extension vaut css (feuille de style) ou json (variables) ; timeout vaut 10 000 ms |
Autres champs
| Champ | Type | Description |
|---|---|---|
debug | booléen | journalise l'initialisation et les changements de langue dans la console du navigateur |
Hooks
Tous les hooks s'utilisent dans un composant client placé sous WakaProvider, sauf useToast qui demande seulement un <Toaster /> rendu dans la page.
| Hook | Renvoie |
|---|---|
useWaka() | currentLanguage, changeLanguage(code), languages, isLanguageLoading, currentTheme, changeTheme(id), themes, isThemeLoading, preloadTheme(id), isThemeLoaded(id), t |
useTheme() | currentTheme, themes, changeTheme(id), isLoading, isDarkMode, toggleDarkMode(), preloadTheme(id), isThemeLoaded(id) |
useLanguage() | currentLanguage, languages, changeLanguage(code), isLoading |
useTranslation() | t, i18n (i18next) |
useToast() | toast({ title, description, variant }), dismiss(id?), toasts |
toast affiche une notification à la fois ; variant vaut default ou destructive.
Variables de couleur
Chaque couleur s'écrit en trois composantes HSL sans fonction, par exemple --primary: 221.2 83.2% 53.3%.
| Variable | Rôle |
|---|---|
--background, --foreground | fond et texte de la page |
--card, --card-foreground | cartes |
--popover, --popover-foreground | menus, listes déroulantes, info-bulles |
--primary, --primary-foreground | action principale, liens |
--secondary, --secondary-foreground | actions secondaires, surfaces atténuées |
--muted, --muted-foreground | surfaces neutres, textes d'aide |
--accent, --accent-foreground | survol, sélection |
--destructive, --destructive-foreground | erreurs, suppressions |
--success, --warning, --info et leurs -foreground | états |
--border, --input, --ring | bordures, champs, anneau de focus |
--chart-1 à --chart-5 | séries des graphiques |
--radius | arrondi de base, par exemple 0.5rem |
Les thèmes intégrés sont default, forest, twilight, sunset, monochrome et perpetuity. Un thème se définit sur [data-theme="<id>"] pour le mode clair et [data-theme="<id>"].dark pour le mode sombre.
Mémorisation dans le navigateur
waka-ui conserve les choix de l'utilisateur dans le localStorage :
| Clé | Contenu |
|---|---|
waka-theme | identifiant du dernier thème appliqué |
waka-dark-mode | dark ou light |
waka-ui-language (ou la valeur de language.storageKey) et language | code de la dernière langue choisie |
Effacez ces clés pour revenir aux valeurs de la configuration.
Ligne de commande
Le paquet installe la commande wakastellar-ui. Elle copie le code source d'un composant dans votre projet, pour le modifier librement ; vous en assurez ensuite vous-même la maintenance. Pour utiliser les composants tels que publiés, l'import depuis le paquet suffit.
| Commande | Effet |
|---|---|
npx wakastellar-ui init | crée components.json et les dossiers components/ui, components/waka, components/blocks, lib, hooks. --yes garde les choix par défaut |
npx wakastellar-ui add button card | copie les composants et ceux dont ils dépendent ; --overwrite remplace les fichiers existants ; affiche les paquets npm à installer |
npx wakastellar-ui list | liste les composants ; --category <nom> filtre par catégorie |
npx wakastellar-ui search date | cherche un composant dans les noms, descriptions et catégories |
Lancez ces commandes dans un projet où @wakastellar/ui est déjà installé.