Blog

Qu'est-ce que HeroUI ? Tutoriel HeroUI pour débutants

Mark Ponomarev

Mark Ponomarev

12 June 2025

Qu'est-ce que HeroUI ? Tutoriel HeroUI pour débutants
đź’ˇ
Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée, Tout-en-Un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et remplace Postman à un prix beaucoup plus abordable !
bouton

Pour les développeurs front-end, la demande d'interfaces utilisateur esthétiquement plaisantes, hautement performantes et profondément personnalisables n'a jamais été aussi forte. Les développeurs recherchent constamment des outils capables d'accélérer leur flux de travail sans sacrifier la qualité ou le contrôle créatif. Si les bibliothèques de composants UI monolithiques ont bien servi la communauté pendant des années, un nouveau paradigme émerge – un paradigme qui privilégie la propriété par le développeur, la modularité et l'intégration transparente avec les frameworks modernes. C'est dans ce nouveau paradigme que HeroUI se taille une place.

HeroUI n'est pas juste une autre bibliothèque de composants ; c'est une collection méticuleusement conçue de composants UI réutilisables, conçus pour être intégrés directement dans vos projets. Il défend une philosophie qui donne aux développeurs le contrôle ultime sur leur base de code. Au lieu d'importer des composants opaques à partir d'un module node, vous utilisez l'Interface de Ligne de Commande (CLI) de HeroUI pour ajouter le code source réel des composants dont vous avez besoin dans votre projet. Cette évolution du "copier-coller" signifie que chaque bouton, carte et boîte de dialogue devient une partie de votre propre application, prête à être ajustée, restylée et adaptée à vos besoins spécifiques.

Construit sur les épaules de géants comme React, Tailwind CSS et Next.js, HeroUI fournit les blocs de construction pour créer des interfaces utilisateur belles, accessibles et réactives. Il est conçu pour le développeur moderne qui valorise à la fois la vitesse et la spécificité, offrant un point de départ robuste qui ne vous enferme pas dans un système de conception rigide. Cet article servira de guide complet pour comprendre les principes fondamentaux de HeroUI, l'installer dans votre projet, personnaliser son apparence et exploiter sa puissante CLI pour construire la prochaine génération d'applications web.

Partie 1 : Déconstruire HeroUI - Philosophie et fonctionnalités clés

Avant de plonger dans les détails techniques de l'installation et de l'utilisation, il est crucial de comprendre le "pourquoi" derrière HeroUI. Quels problèmes résout-il, et qu'est-ce qui en fait un choix convaincant dans un domaine encombré d'outils UI ?

La Philosophie : Propriété et Personnalisation Sans Compromis

La différence fondamentale entre HeroUI et les bibliothèques UI traditionnelles comme Material-UI ou Ant Design réside dans le concept de propriété. Lorsque vous installez une bibliothèque traditionnelle, vous ajoutez une dépendance à votre package.json. Votre application importe ensuite des composants pré-compilés à partir de ce package. Bien que cela soit pratique, cela présente plusieurs inconvénients :

  1. Personnalisation Limitée : Les surcharges de style peuvent être complexes, vous obligeant souvent à lutter contre les styles par défaut de la bibliothèque avec des balises !important ou des configurations de fournisseur de thème compliquées.
  2. Composants Boîtes Noires : La logique interne des composants est cachée dans le dossier node_modules. Déboguer un comportement inattendu ou comprendre le fonctionnement interne devient beaucoup plus difficile.
  3. Gonflement de la Taille du Bundle : Vous importez souvent la bibliothèque entière, ou du moins une partie importante de celle-ci, même si vous n'utilisez qu'une poignée de composants, ce qui peut potentiellement augmenter la taille finale du bundle de votre application.
  4. L'Enfer des Dépendances : Vous êtes lié au cycle de mise à jour de la bibliothèque et à ses dépendances. Un changement majeur dans la bibliothèque peut forcer un refactoring important dans votre application.

HeroUI contourne entièrement ces problèmes. En permettant à la CLI de placer le code source du composant directement dans le répertoire de votre projet (par exemple, /components/ui), il vous donne du pouvoir de plusieurs manières clés :

Cette philosophie s'adresse aux développeurs et aux équipes qui souhaitent construire un système de conception unique pour leur produit sans partir de zéro. Il fournit les primitives fondamentales, non stylisées (ou légèrement stylisées), et vous fournissez l'identité de la marque.

Fonctionnalités Clés en un Coup d'Œil

HeroUI est plus qu'une simple méthode d'installation. Il est doté de fonctionnalités conçues pour un flux de travail de développement moderne.

Ă€ Qui S'Adresse HeroUI ?

HeroUI est un choix idéal pour un type spécifique de développeur et de projet :

Il peut être moins adapté aux débutants absolus qui préfèrent une solution plus "prête à l'emploi", avec tout inclus, où une configuration minimale est requise. Le pouvoir de HeroUI réside dans sa configurabilité, qui nécessite une compréhension fondamentale de Tailwind CSS et de l'environnement de développement front-end moderne.

Partie 2 : Démarrer - Un Guide Détaillé de l'Installation et de la Configuration

Maintenant que nous comprenons la philosophie, passons à la pratique. Cette section fournit un guide méticuleux, étape par étape, pour intégrer HeroUI dans un projet nouveau ou existant. La méthode recommandée et la plus efficace est d'utiliser la CLI officielle de HeroUI.

Prérequis

Avant de commencer, assurez-vous que votre environnement de développement répond aux exigences suivantes :

npx create-next-app@latest my-heroui-app

Lors de la configuration de Next.js, il est recommandé de choisir TypeScript et Tailwind CSS, car ils sont fondamentaux pour l'écosystème HeroUI.

La Commande init de l'Interface de Ligne de Commande (CLI) HeroUI : Votre Point de DĂ©part

La commande init est le point d'entrée magique dans le monde de HeroUI. Elle inspecte intelligemment votre projet, vous pose une série de questions, puis configure automatiquement tout ce dont vous avez besoin.

Naviguez dans le répertoire de votre projet :Bash

cd my-heroui-app

Maintenant, exécutez la commande d'initialisation :Bash

npx heroui-cli@latest init

La CLI va maintenant vous guider Ă  travers le processus de configuration. DĂ©composons chaque question qu'elle pose et ce que signifient vos choix.

1. "Quel style souhaitez-vous utiliser ?"

2. "Quelle couleur souhaitez-vous utiliser comme couleur de base ?"

3. "OĂą se trouve votre fichier CSS global ?"

4. "Voulez-vous utiliser des variables CSS pour les couleurs ?"

5. "OĂą se trouve votre fichier tailwind.config.js ?"

6. "Configurer l'alias d'importation pour les composants :"

7. "Configurer l'alias d'importation pour les utilitaires :"

8. "Utilisez-vous des Composants Serveur React ?"

Une fois que vous avez répondu à toutes les questions, la CLI accomplira sa magie. Elle va :

Votre projet est maintenant entièrement configuré et prêt pour HeroUI.

Anatomie des Changements

Examinons de plus près les fichiers clés que la CLI a modifiés ou créés.

components.json

Ce fichier est le manifeste de HeroUI au sein de votre projet. Il stocke les choix que vous avez faits pendant le processus init et indique à la CLI comment votre projet est configuré.JSON

{
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "utils": "@/lib/utils",
    "components": "@/components"
  }
}

Vous devriez rarement avoir besoin de modifier ce fichier manuellement, mais il est utile de comprendre son objectif. C'est le cerveau derrière les opérations de la CLI.

tailwind.config.js

Votre configuration Tailwind sera étendue pour ressembler à ceci. Les ajouts clés sont les extensions theme et le plugin tailwindcss-animate.JavaScript

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: [
    './pages/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
    './src/**/*.{ts,tsx}',
  ],
  theme: {
    container: {
      center: true,
      padding: "2rem",
      screens: {
        "2xl": "1400px",
      },
    },
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        // ... et bien d'autres définitions de couleurs liées aux variables CSS
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        // ...
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      keyframes: {
        // ... keyframes pour les animations
      },
      animation: {
        // ... utilitaires d'animation
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

Notez comment les couleurs comme primary ne sont pas définies avec un code hexadécimal mais avec hsl(var(--primary)). Cela indique à Tailwind d'utiliser la variable CSS nommée --primary, qui est définie dans votre CSS global.

app/globals.css

Ce fichier est maintenant le cœur du thème de votre système de conception. Il contiendra les directives Tailwind de base et un grand bloc de variables CSS.CSS

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    /* ... de nombreuses autres variables pour le thème clair */
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    /* ... de nombreuses autres variables pour le thème sombre */
  }
}

Ici, vous pouvez voir la puissance de cette configuration. Toutes vos couleurs de thème clair sont définies dans la portée :root, et toutes vos couleurs de thème sombre sont définies dans la portée de la classe .dark. Lorsque la classe .dark est ajoutée à l'élément <html>, le navigateur utilisera automatiquement les variables du thème sombre.

Partie 3 : Maîtriser la Personnalisation - Thème, Mise en Page et Mode Sombre

Avec HeroUI initialisé, le vrai plaisir commence : le personnaliser. L'architecture est explicitement conçue pour une personnalisation profonde et intuitive.

L'Art du Thème avec les Variables CSS

Le theming dans HeroUI est un départ par rapport aux objets de thème complexes basés sur JavaScript que vous pourriez trouver dans d'autres bibliothèques. C'est plus simple, plus puissant et exploite les fonctionnalités CSS modernes. L'ensemble du thème — couleurs, rayons de bordure, polices — est contrôlé par des variables CSS définies dans votre fichier globals.css.

Changer les Couleurs

Supposons que vous souhaitiez changer la couleur principale de votre marque. Vous n'avez pas besoin d'aller dans la configuration Tailwind. Vous trouvez simplement les variables CSS pertinentes dans globals.css et modifiez leurs valeurs.

Les couleurs sont définies à l'aide de valeurs HSL (Teinte, Saturation, Luminosité), mais sans l'enveloppe hsl(). Par exemple :CSS

:root {
  /* ... */
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}

.dark {
  /* ... */
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}

Pour changer votre couleur principale en un vert éclatant, vous pouvez utiliser un sélecteur de couleurs en ligne pour trouver les valeurs HSL de la nuance choisie et mettre à jour les variables :CSS

/* Dans globals.css */
:root {
  /* ... */
  --primary: 142.1 76.2% 36.3%; /* Nouvelle couleur principale verte */
  --primary-foreground: 355.7 100% 97.3%; /* Une couleur claire contrastante pour le texte sur la couleur principale */
  /* ... */
}

.dark {
  /* ... */
  --primary: 142.1 70.2% 46.3%; /* Un vert légèrement différent pour le mode sombre */
  --primary-foreground: 355.7 100% 97.3%;
  /* ... */
}

Une fois que vous enregistrez ce fichier, chaque composant qui utilise la couleur "primary" (comme <Button>) se mettra instantanément à jour dans toute votre application pour refléter cette nouvelle couleur verte. C'est incroyablement puissant.

Changer le Rayon de Bordure

La rondeur des coins des composants comme les cartes et les champs de saisie est contrôlée par une seule variable CSS : --radius.CSS

/* Dans globals.css */
:root {
  /* ... */
  --radius: 0.5rem; /* La valeur par défaut */
}

Si vous préférez un look plus net et plus carré, vous pouvez réduire cette valeur :CSS

:root {
  --radius: 0.25rem; /* Moins arrondi */
}

Ou, pour une esthétique très douce et arrondie, vous pouvez l'augmenter :CSS

:root {
  --radius: 1.5rem; /* Très arrondi */
}

Ce changement d'une seule ligne se propagera à tous vos composants, assurant un rayon de bordure cohérent dans toute votre UI.

Ajouter de Nouvelles Couleurs

Vous n'êtes pas limité aux couleurs fournies par la commande init. Vous pouvez facilement ajouter vos propres couleurs sémantiques. Par exemple, ajoutons une couleur de marque "spéciale".

DĂ©finir les variables CSS dans globals.css :CSS

/* Dans globals.css */
:root {
  /* ... */
  --special: 320 86% 59%;
  --special-foreground: 330 100% 98%;
}
.dark {
  /* ... */
  --special: 320 80% 69%;
  --special-foreground: 330 100% 98%;
}

Les exposer Ă  Tailwind dans tailwind.config.js :JavaScript

// Dans tailwind.config.js
// ...
extend: {
  colors: {
    // ...
    special: {
      DEFAULT: "hsl(var(--special))",
      foreground: "hsl(var(--special-foreground))",
    },
  },
},
// ...

Vous pouvez maintenant utiliser ces couleurs dans vos composants avec les classes utilitaires de Tailwind, telles que bg-special et text-special-foreground.

Construire des Mises en Page RĂ©actives

Les composants HeroUI sont construits avec Tailwind CSS, ce qui signifie qu'ils sont intrinsèquement réactifs. Vous pouvez utiliser les préfixes réactifs de Tailwind (sm:, md:, lg:, xl:) sur n'importe quelle classe utilitaire pour modifier le style d'un composant à différentes tailles d'écran.

Imaginons la construction d'une mise en page simple avec une barre latérale visible sur ordinateur mais qui se réduit sur mobile. Bien que HeroUI fournisse les composants de bas niveau (Card, Button), vous êtes responsable de leur composition en une mise en page plus large.

Voici un exemple de la façon dont vous pourriez structurer cela dans un composant de page Next.js :TypeScript

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

export default function DashboardPage() {
  return (
    <div className="flex min-h-screen flex-col md:flex-row">
      {/* Barre latérale */}
      <aside className="w-full border-b bg-muted p-4 md:w-64 md:border-b-0 md:border-r">
        <h2 className="text-lg font-semibold">Navigation</h2>
        <nav className="mt-4 flex flex-row space-x-2 md:flex-col md:space-x-0 md:space-y-2">
          <Button variant="ghost" className="justify-start">Tableau de bord</Button>
          <Button variant="ghost" className="justify-start">Paramètres</Button>
          <Button variant="ghost" className="justify-start">Profil</Button>
        </nav>
      </aside>

      {/* Contenu principal */}
      <main className="flex-1 p-8">
        <h1 className="text-4xl font-bold tracking-tight">Tableau de bord</h1>
        <p className="mt-2 text-muted-foreground">
          Bienvenue sur votre tableau de bord.
        </p>
        <div className="mt-8 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
          <Card>
            <CardHeader>
              <CardTitle>Revenus</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">$45,231.89</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Abonnements</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+2350</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Utilisateurs Actifs</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+573</p>
            </CardContent>
          </Card>
        </div>
      </main>
    </div>
  );
}

Dans cet exemple :

Cela démontre le principe fondamental : HeroUI fournit les primitives stylisées (Card, Button), et vous utilisez toute la puissance de Tailwind CSS pour les organiser en mises en page réactives et complexes.

Implémenter un Mode Sombre Impeccable

L'une des fonctionnalités les plus élégantes de HeroUI est son support intégré pour le mode sombre. Étant donné que la commande init a déjà configuré les variables de couleur pour les thèmes clair (:root) et sombre (.dark), son implémentation est étonnamment simple.

L'approche la plus courante consiste à utiliser le package next-themes, qui gère la commutation de thème et persiste le choix de l'utilisateur dans le stockage local.

Installer next-themes :Bash

npm install next-themes

Créer un Fournisseur de Thème :

Créer un nouveau fichier, par exemple, dans components/theme-provider.tsx.TypeScript

"use client";

import * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";
import { type ThemeProviderProps } from "next-themes/dist/types";

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}

Envelopper Votre Layout Racine avec le Fournisseur :

Dans votre layout racine Next.js (app/layout.tsx), importer et utiliser le ThemeProvider.TypeScript

import { ThemeProvider } from "@/components/theme-provider";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={inter.className}>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Les props clés ici sont :

Créer un Bouton de Bascule de Thème :

Maintenant, il vous suffit d'un élément d'interface utilisateur pour permettre à l'utilisateur de changer de thème.TypeScript

"use client";

import * as React from "react";
import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";

export function ModeToggle() {
  const { setTheme, theme } = useTheme();

  const toggleTheme = () => {
    setTheme(theme === "light" ? "dark" : "light");
  };

  return (
    <Button variant="outline" size="icon" onClick={toggleTheme}>
      <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Basculer le thème</span>
    </Button>
  );
}

Ce1 composant utilise le hook useTheme de next-themes pour vérifier le thème actuel et en définir un nouveau. Les icônes rotatives du soleil et de la lune offrent une belle transition visuelle. Placez simplement ce composant <ModeToggle /> quelque part dans votre UI (comme un en-tête), et vous aurez un bouton de bascule de mode sombre entièrement fonctionnel et persistant.

Partie 4 : L'Interface de Ligne de Commande (CLI) HeroUI et son Workflow Centré sur les Composants

Le heroui-cli est plus qu'un simple programme d'installation. C'est l'outil principal que vous utiliserez pour gérer et développer votre bibliothèque de composants. Son objectif principal après l'initialisation est d'ajouter de nouveaux composants à votre projet.

Ajouter des Composants : Le Workflow Principal

Supposons que vous ayez besoin d'une boîte de dialogue modale pour votre application. Au lieu d'en écrire une à partir de zéro, vous pouvez demander à la CLI d'ajouter le composant Dialog pré-construit et accessible de HeroUI.

La commande est simple :Bash

npx heroui-cli@latest add dialog

La CLI effectuera les actions suivantes :

  1. Elle lit votre fichier components.json pour comprendre la structure de votre projet (alias de chemin, utilisation de TypeScript, etc.).
  2. Elle récupère le code source le plus récent du composant Dialog et de toutes ses dépendances (par exemple, Dialog peut dépendre de Button).
  3. Elle place les fichiers du composant directement dans votre répertoire de composants, par exemple : components/ui/dialog.tsx.
  4. Elle vous informera de toute autre dépendance que vous pourriez avoir besoin d'installer.

Maintenant, vous avez un fichier dialog.tsx dans votre projet. Vous pouvez inspecter son code, en tirer des leçons et même le modifier. Si le Dialog par défaut a une transition que vous n'aimez pas, vous pouvez simplement ouvrir le fichier et modifier les classes Tailwind qui contrôlent l'animation. Ce niveau de contrôle est la pierre angulaire de l'expérience HeroUI.

Vous pouvez ajouter plusieurs composants Ă  la fois :Bash

npx heroui-cli@latest add card button input label

Cette commande ajoutera les quatre composants et leurs dépendances à votre projet en une seule fois.

Comprendre l'API de la CLI : components.json

Le fichier components.json est le contrat entre votre projet et la CLI HeroUI. Revoyons ses propriétés pour comprendre comment elles influencent le comportement de la CLI.

En comprenant cette configuration, vous pouvez même ajuster manuellement le comportement de la CLI si vous décidez de refactoriser la structure de votre projet, par exemple, en déplaçant votre répertoire de composants de @/components à @/ui.

Conclusion : Construisez à Votre Façon avec HeroUI

HeroUI représente un changement significatif dans la manière dont les développeurs peuvent concevoir et utiliser les bibliothèques UI. Il s'éloigne du modèle unique et boîte noire pour aller vers une expérience développeur transparente, responsabilisante et profondément personnalisable. En fournissant des composants non stylisés et accessibles directement sous forme de code source, il trouve l'équilibre parfait entre le développement rapide et la conception sur mesure.

Les points forts de HeroUI sont clairs :

HeroUI s'adresse aux constructeurs, aux artisans et aux équipes qui croient que leur interface utilisateur est une partie essentielle de l'identité de leur produit. Il ne vous donne pas une maison finie ; il vous donne les matériaux de la plus haute qualité et un atelier parfaitement organisé pour construire la maison de vos rêves. Pour votre prochain projet qui exige un front-end unique, soigné et maintenable, ne cherchez pas plus loin que HeroUI. C'est peut-être l'outil qui vous permettra de construire votre UI la plus héroïque à ce jour.

đź’ˇ
Vous voulez un excellent outil de test d'API qui génère une belle documentation API ?

Vous voulez une plateforme intégrée, Tout-en-Un, pour que votre équipe de développeurs travaille ensemble avec une productivité maximale ?

Apidog répond à toutes vos exigences et replaces Postman at a much more affordable price !
bouton

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger