Aller au contenu

Installer waka-ui

Ajouter @wakastellar/ui à une application Next.js - paquet, styles Tailwind CSS 4, fournisseur WakaProvider et premier composant.

Démarrage rapideDéveloppeur
Durée
15 min
Voir en Markdown

Ce guide met en place waka-ui dans une application Next.js (App Router) qui utilise Tailwind CSS 4. À la fin, votre page affiche une carte et un bouton aux couleurs du thème par défaut, et un clic sur le bouton affiche une notification.

Avant de commencer

  • Votre projet utilise Next.js 14 ou plus, React 18 ou plus, et l'App Router. waka-ui est testé sur Next.js 16 et React 19.
  • Tailwind CSS 4 est déjà configuré : le fichier postcss.config.mjs déclare le plugin @tailwindcss/postcss. C'est le cas d'un projet créé par create-next-app avec l'option Tailwind.
  • Node.js 22 ou plus.

Le paquet est public : aucun jeton ni registre particulier n'est nécessaire. Votre projet est en Tailwind CSS 3.4 ? Suivez les étapes de la référence à la place de l'étape 2.

Installer le paquet

Installez @wakastellar/ui avec deux dépendances que son point d'entrée principal référence : recharts (graphiques) et react-hook-form (formulaires).

Bash
npm install @wakastellar/ui recharts@^2 react-hook-form

Avec pnpm : pnpm add @wakastellar/ui recharts@^2 react-hook-form.

Les autres dépendances facultatives (éditeurs, export Excel ou PDF) ne servent qu'aux points d'entrée dédiés : installez-les seulement si vous les utilisez, voir Composants et blocks.

Importer les styles

En tête de app/globals.css, à la place de la ligne @import "tailwindcss", écrivez :

CSS
/* Styles de waka-ui : ils incluent déjà Tailwind CSS. */
@import "@wakastellar/ui/styles";

/* Mode sombre piloté par la classe .dark que pose waka-ui sur <html>. */
@custom-variant dark (&:where(.dark, .dark *));

/* Tailwind n'analyse pas node_modules : déclarez les composants compilés de waka-ui. */
@source "../node_modules/@wakastellar/ui/dist";

N'ajoutez pas @import "tailwindcss" en plus : la feuille de waka-ui l'importe déjà. Le chemin de @source est relatif au fichier CSS ; si votre CSS global est dans src/app/, écrivez ../../node_modules/@wakastellar/ui/dist.

Déclarer le fournisseur

Créez app/providers.tsx :

TSX
"use client";

import type { ReactNode } from "react";
import { Toaster, WakaProvider, type WakaProviderConfig } from "@wakastellar/ui";

// Définie hors du composant : la même configuration est réutilisée à chaque rendu.
const config: WakaProviderConfig = {
  language: {
    defaultLanguage: "fr",
    supportedLanguages: ["fr", "en"],
    languages: [
      { code: "fr", label: "Français" },
      { code: "en", label: "English" },
    ],
  },
  theme: {
    defaultTheme: "default",
    themes: [{ id: "default", label: "Par défaut" }],
    enableSystem: true,
  },
};

export function Providers({ children }: { children: ReactNode }) {
  return (
    <WakaProvider config={config}>
      {children}
      <Toaster />
    </WakaProvider>
  );
}

enableSystem: true active le mode sombre : à sa première visite, l'utilisateur reçoit le mode de son système, puis son choix est mémorisé dans le navigateur. <Toaster /> affiche les notifications envoyées par useToast.

Envelopper l'application

Dans app/layout.tsx :

TSX
import type { ReactNode } from "react";
import "./globals.css";
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="fr">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Afficher un premier composant

Remplacez app/page.tsx :

TSX
"use client";

import { Button, Card, CardContent, CardHeader, CardTitle, useToast } from "@wakastellar/ui";

export default function Page() {
  const { toast } = useToast();

  return (
    <Card className="m-8 max-w-md">
      <CardHeader>
        <CardTitle>Bienvenue</CardTitle>
      </CardHeader>
      <CardContent>
        <Button onClick={() => toast({ title: "Enregistré", description: "Vos modifications sont prises en compte." })}>
          Enregistrer
        </Button>
      </CardContent>
    </Card>
  );
}

Vérifier le résultat

  1. Lancez npm run dev et ouvrez la page.
  2. La carte s'affiche avec une bordure et un fond, et le bouton est plein, en couleur primaire.
  3. Cliquez sur Enregistrer : la notification « Enregistré » apparaît.
  4. Passez votre système en mode sombre et ouvrez la page dans une fenêtre de navigation privée : l'interface s'affiche en sombre.

Une carte sans bordure ou un bouton transparent signale presque toujours une ligne @source manquante : voir Résoudre les problèmes de waka-ui.

Voir aussi