Blog

¿Qué es HeroUI? Tutorial de HeroUI para Principiantes

Mark Ponomarev

Mark Ponomarev

12 June 2025

¿Qué es HeroUI? Tutorial de HeroUI para Principiantes
💡
¿Quiere una excelente herramienta de pruebas de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada y todo en uno para que su equipo de desarrolladores trabaje junto con la máxima productividad?

Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!
botón

Para los desarrolladores frontend, la demanda de interfaces de usuario estéticamente agradables, de alto rendimiento y profundamente personalizables nunca ha sido mayor. Los desarrolladores buscan constantemente herramientas que puedan acelerar su flujo de trabajo sin sacrificar la calidad o el control creativo. Si bien las bibliotecas monolíticas de componentes de UI han servido bien a la comunidad durante años, está surgiendo un nuevo paradigma, uno que prioriza la propiedad del desarrollador, la modularidad y la integración perfecta con los frameworks modernos. Es dentro de este nuevo paradigma donde HeroUI se labra su nicho.

HeroUI no es solo otra biblioteca de componentes; es una colección meticulosamente elaborada de componentes de UI reutilizables diseñados para integrarse directamente en sus proyectos. Defiende una filosofía que otorga a los desarrolladores el control total sobre su base de código. En lugar de importar componentes opacos de un módulo de node, utiliza la Interfaz de Línea de Comandos (CLI) de HeroUI para agregar el código fuente real de los componentes que necesita a su proyecto. Esta evolución de "copiar y pegar" significa que cada botón, tarjeta y cuadro de diálogo se convierte en parte de su propia aplicación, listo para ser ajustado, rediseñado y adaptado a sus necesidades específicas.

Construido sobre los hombros de gigantes como React, Tailwind CSS y Next.js, HeroUI proporciona los bloques de construcción para crear interfaces de usuario hermosas, accesibles y receptivas. Está diseñado para el desarrollador moderno que valora tanto la velocidad como la especificidad, ofreciendo un punto de partida robusto que no lo encierra en un sistema de diseño rígido. Este artículo servirá como una guía completa para comprender los principios fundamentales de HeroUI, instalarlo en su proyecto, personalizar su apariencia y aprovechar su potente CLI para construir la próxima generación de aplicaciones web.

Parte 1: Deconstruyendo HeroUI - Filosofía y Características Principales

Antes de sumergirse en los detalles técnicos de la instalación y el uso, es crucial comprender el "por qué" detrás de HeroUI. ¿Qué problemas resuelve y qué lo convierte en una opción atractiva en un campo abarrotado de herramientas de UI?

La Filosofía: Propiedad y Personalización Sin Compromisos

La diferencia fundamental entre HeroUI y las bibliotecas de UI tradicionales como Material-UI o Ant Design radica en el concepto de propiedad. Cuando instala una biblioteca tradicional, agrega una dependencia a su package.json. Su aplicación luego importa componentes precompilados de este paquete. Si bien esto es conveniente, conlleva varios inconvenientes:

  1. Personalización Limitada: Anular estilos puede ser complejo, a menudo requiriendo que luche contra los estilos predeterminados de la biblioteca con etiquetas !important o configuraciones complicadas de proveedores de temas.
  2. Componentes de Caja Negra: La lógica interna de los componentes está oculta en la carpeta node_modules. Depurar comportamientos inesperados o comprender el funcionamiento interno se vuelve significativamente más difícil.
  3. Inflado del Tamaño del Bundle: A menudo importa toda la biblioteca, o al menos una parte significativa de ella, incluso si solo usa un puñado de componentes, lo que potencialmente aumenta el tamaño final del bundle de su aplicación.
  4. Infierno de Dependencias: Está sujeto al ciclo de actualización de la biblioteca y sus dependencias. Un cambio importante en la biblioteca puede forzar una refactorización importante en su aplicación.

HeroUI evita por completo estos problemas. Al hacer que la CLI coloque el código fuente del componente directamente en el directorio de su proyecto (por ejemplo, /components/ui), lo empodera de varias maneras clave:

Esta filosofía está dirigida a desarrolladores y equipos que desean construir un sistema de diseño único para su producto sin empezar desde cero. Proporciona las primitivas fundamentales, sin estilo (o con un estilo ligero), y usted proporciona la identidad de marca.

Características Clave de un Vistazo

HeroUI es más que solo su método de instalación. Viene repleto de características diseñadas para un flujo de trabajo de desarrollo moderno.

¿Para Quién Es HeroUI?

HeroUI es una opción ideal para un tipo específico de desarrollador y proyecto:

Puede ser menos adecuado para principiantes absolutos que prefieren una solución más "lista para usar", con todo incluido, donde se requiere una configuración mínima. El poder de HeroUI reside en su configurabilidad, que requiere una comprensión fundamental de Tailwind CSS y el entorno de desarrollo frontend moderno.

Parte 2: Primeros Pasos - Un Recorrido Detallado por la Instalación y Configuración

Ahora que entendemos la filosofía, pongámonos manos a la obra. Esta sección proporciona una guía meticulosa y paso a paso para integrar HeroUI en un proyecto nuevo o existente. El método recomendado y más eficiente es usar la CLI oficial de HeroUI.

Requisitos Previos

Antes de comenzar, asegúrese de que su entorno de desarrollo cumpla los siguientes requisitos:

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

Durante la configuración de Next.js, se recomienda elegir TypeScript y Tailwind CSS, ya que son fundamentales para el ecosistema de HeroUI.

El Comando init de la CLI de HeroUI: Su Punto de Partida

El comando init es el punto de entrada mágico al mundo de HeroUI. Inspecciona inteligentemente su proyecto, le hace una serie de preguntas y luego configura automáticamente todo lo que necesita.

Navegue al directorio de su proyecto:Bash

cd my-heroui-app

Ahora, ejecute el comando de inicialización:Bash

npx heroui-cli@latest init

La CLI ahora lo guiará a través del proceso de configuración. Analicemos cada pregunta que hace y lo que significan sus elecciones.

1. "¿Qué estilo le gustaría usar?"

2. "¿Qué color le gustaría usar como color base?"

3. "¿Dónde está su archivo CSS global?"

4. "¿Desea usar variables CSS para los colores?"

5. "¿Dónde está su archivo tailwind.config.js?"

6. "Configurar alias de importación para componentes:"

7. "Configurar alias de importación para utilidades:"

8. "¿Está utilizando React Server Components?"

Una vez que haya respondido todas las preguntas, la CLI realizará su magia. Hará lo siguiente:

Su proyecto ahora está completamente configurado y listo para HeroUI.

Anatomía de los Cambios

Veamos más de cerca los archivos clave que la CLI ha modificado o creado.

components.json

Este archivo es el manifiesto de HeroUI dentro de su proyecto. Almacena las elecciones que hizo durante el proceso init e indica a la CLI cómo está configurado su proyecto.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"
  }
}

Rara vez necesitará editar este archivo manualmente, pero es útil comprender su propósito. Es el cerebro detrás de las operaciones de la CLI.

tailwind.config.js

Su configuración de Tailwind se extenderá para verse algo así. Las adiciones clave son las extensiones de theme y el 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))",
        // ... and many more color definitions linked to CSS variables
        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 for animations
      },
      animation: {
        // ... animation utilities
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

Observe cómo los colores como primary no se definen con un código hexadecimal, sino con hsl(var(--primary)). Esto le indica a Tailwind que use la variable CSS llamada --primary, que está definida en su CSS global.

app/globals.css

Este archivo es ahora el corazón del tema de su sistema de diseño. Contendrá las directivas base de Tailwind y un gran bloque 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%;
    /* ... many more variables for the light theme */
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    /* ... many more variables for the dark theme */
  }
}

Aquí puede ver el poder de esta configuración. Todos los colores de su tema claro se definen en el ámbito :root, y todos los colores de su tema oscuro se definen dentro del ámbito de la clase .dark. Cuando la clase .dark se agrega al elemento <html>, el navegador usará automáticamente las variables del tema oscuro.

Parte 3: Dominando la Personalización - Theming, Diseño y Modo Oscuro

Con HeroUI inicializado, comienza la verdadera diversión: hacerlo suyo. La arquitectura está diseñada explícitamente para una personalización profunda e intuitiva.

El Arte del Theming con Variables CSS

El theming en HeroUI se aleja de los complejos objetos de tema basados en JavaScript que podría encontrar en otras bibliotecas. Es más simple, más potente y aprovecha las características modernas de CSS. Todo el tema (colores, radios de borde, fuentes) se controla mediante variables CSS definidas en su globals.css file.

Cambiando Colores

Supongamos que desea cambiar el color principal de su marca. No necesita ir a la configuración de Tailwind. Simplemente encuentra las variables CSS relevantes en globals.css y cambia sus valores.

Los colores se definen utilizando valores HSL (Tono, Saturación, Luminosidad), pero sin el envoltorio hsl(). Por ejemplo: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%;
  /* ... */
}

Para cambiar su color principal a un verde vibrante, podría usar un selector de color en línea para encontrar los valores HSL de su tono elegido y actualizar las variables:CSS

/* In globals.css */
:root {
  /* ... */
  --primary: 142.1 76.2% 36.3%; /* New Green Primary Color */
  --primary-foreground: 355.7 100% 97.3%; /* A contrasting light color for text on the primary color */
  /* ... */
}

.dark {
  /* ... */
  --primary: 142.1 70.2% 46.3%; /* A slightly different green for dark mode */
  --primary-foreground: 355.7 100% 97.3%;
  /* ... */
}

Una vez que guarde este archivo, cada componente que use el color "primary" (como <Button>) se actualizará instantáneamente en toda su aplicación para reflejar este nuevo color verde. Esto es increíblemente potente.

Cambiando el Radio del Borde

La redondez de las esquinas en componentes como tarjetas y campos de entrada se controla mediante una única variable CSS: --radius.CSS

/* In globals.css */
:root {
  /* ... */
  --radius: 0.5rem; /* The default value */
}

Si prefiere un aspecto más nítido y cuadrado, puede reducir este valor:CSS

:root {
  --radius: 0.25rem; /* Less rounded */
}

O, para una estética muy suave y redondeada, puede aumentarlo:CSS

:root {
  --radius: 1.5rem; /* Very rounded */
}

Este cambio de una sola línea se propagará a través de todos sus componentes, asegurando un radio de borde consistente en toda su UI.

Agregando Nuevos Colores

No está limitado a los colores proporcionados por el comando init. Puede agregar fácilmente sus propios colores semánticos. Por ejemplo, agreguemos un color de marca "especial".

Defina las variables CSS en globals.css:CSS

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

Expóngalos a Tailwind en tailwind.config.js:JavaScript

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

Ahora puede usar estos colores en sus componentes con las clases de utilidad de Tailwind, como bg-special y text-special-foreground.

Construyendo Diseños Responsivos

Los componentes de HeroUI están construidos con Tailwind CSS, lo que significa que son inherentemente responsivos. Puede usar los prefijos responsivos de Tailwind (sm:, md:, lg:, xl:) en cualquier clase de utilidad para cambiar el estilo de un componente en diferentes tamaños de pantalla.

Imaginemos construir un diseño de página simple con una barra lateral que sea visible en escritorio pero se colapse en móvil. Si bien HeroUI proporciona los componentes de bajo nivel (Card, Button), usted es responsable de componerlos en un diseño más grande.

Aquí hay un ejemplo de cómo podría estructurar esto en un componente de página de 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">
      {/* Sidebar */}
      <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">Navegación</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">Panel de Control</Button>
          <Button variant="ghost" className="justify-start">Configuración</Button>
          <Button variant="ghost" className="justify-start">Perfil</Button>
        </nav>
      </aside>

      {/* Main Content */}
      <main className="flex-1 p-8">
        <h1 className="text-4xl font-bold tracking-tight">Panel de Control</h1>
        <p className="mt-2 text-muted-foreground">
          Bienvenido a su panel de control.
        </p>
        <div className="mt-8 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
          <Card>
            <CardHeader>
              <CardTitle>Ingresos</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">$45,231.89</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Suscripciones</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+2350</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Usuarios Activos</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+573</p>
            </CardContent>
          </Card>
        </div>
      </main>
    </div>
  );
}

En este ejemplo:

Esto demuestra el principio fundamental: HeroUI proporciona las primitivas con estilo (Card, Button), y usted utiliza todo el poder de Tailwind CSS para organizarlas en diseños responsivos y complejos.

Implementando un Modo Oscuro Impecable

Una de las características más elegantes de HeroUI es su soporte integrado para el modo oscuro. Dado que el comando init ya configuró las variables de color tanto para temas claros (:root) como oscuros (.dark), implementarlo es sorprendentemente simple.

El enfoque más común es usar el paquete next-themes, que maneja el cambio de tema y persiste la elección del usuario en el almacenamiento local.

Instalar next-themes:Bash

npm install next-themes

Crear un Proveedor de Tema:

Cree un nuevo archivo, por ejemplo, en 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>;
}

Envuelva su Diseño Raíz con el Proveedor:

En su diseño raíz de Next.js (app/layout.tsx), importe y use el 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: "Crear Aplicación Next",
  description: "Generada por 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>
  );
}

Las propiedades clave aquí son:

Crear un Botón de Alternancia de Tema:

Ahora, solo necesita un elemento de UI para permitir al usuario cambiar de tema.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">Alternar tema</span>
    </Button>
  );
}

Este componente utiliza el hook useTheme de next-themes para verificar el tema actual y establecer uno nuevo. Los iconos giratorios del sol y la luna proporcionan una agradable transición visual. Simplemente coloque este componente <ModeToggle /> en algún lugar de su UI (como un encabezado), y tendrá un alternador de modo oscuro completamente funcional y persistente.

Parte 4: La CLI de HeroUI y su Flujo de Trabajo Centrado en Componentes

La heroui-cli es más que solo un instalador. Es la herramienta principal que utilizará para gestionar y hacer crecer su biblioteca de componentes. Su propósito principal después de la inicialización es agregar nuevos componentes a su proyecto.

Agregando Componentes: El Flujo de Trabajo Principal

Supongamos que necesita un modal de diálogo para su aplicación. En lugar de escribir uno desde cero, puede pedirle a la CLI que agregue el componente Dialog preconstruido y accesible de HeroUI.

El comando es simple:Bash

npx heroui-cli@latest add dialog

La CLI realizará las siguientes acciones:

  1. Lee su archivo components.json para comprender la estructura de su proyecto (alias de ruta, uso de TypeScript, etc.).
  2. Obtiene el código fuente más reciente para el componente Dialog y cualquiera de sus dependencias (por ejemplo, Dialog podría depender de Button).
  3. Coloca los archivos del componente directamente en su directorio de componentes, por ejemplo: components/ui/dialog.tsx.
  4. Le informará de cualquier otra dependencia que pueda necesitar instalar.

Ahora, tiene un archivo dialog.tsx en su proyecto. Puede inspeccionar su código, aprender de él e incluso modificarlo. Si el Dialog predeterminado tiene una transición que no le gusta, simplemente puede abrir el archivo y cambiar las clases de Tailwind que controlan la animación. Este nivel de control es la piedra angular de la experiencia de HeroUI.

Puede agregar varios componentes a la vez:Bash

npx heroui-cli@latest add card button input label

Este comando agregará los cuatro componentes y sus dependencias a su proyecto de una sola vez.

Comprendiendo la API de la CLI: components.json

El archivo components.json es el contrato entre su proyecto y la CLI de HeroUI. Revisitemos sus propiedades para comprender cómo influyen en el comportamiento de la CLI.

Al comprender esta configuración, incluso puede ajustar manualmente el comportamiento de la CLI si decide refactorizar la estructura de su proyecto, por ejemplo, moviendo su directorio de componentes de @/components a @/ui.

Conclusión: Construya a Su Manera con HeroUI

HeroUI representa un cambio significativo en la forma en que los desarrolladores pueden pensar y usar las bibliotecas de UI. Se aleja del modelo de caja negra, único para todos, y se dirige hacia una experiencia de desarrollador transparente, empoderadora y profundamente personalizable. Al proporcionar componentes accesibles y sin estilo directamente como código fuente, logra el equilibrio perfecto entre el desarrollo rápido y el diseño a medida.

Las fortalezas principales de HeroUI son claras:

HeroUI es para los constructores, los artesanos y los equipos que creen que su interfaz de usuario es una parte fundamental de la identidad de su producto. No le da una casa terminada; le da los materiales de la más alta calidad y un taller perfectamente organizado para construir la casa de sus sueños. Para su próximo proyecto que exija un frontend único, pulido y mantenible, no busque más allá de HeroUI. Podría ser la herramienta que lo empodere para construir su UI más heroica hasta ahora.

💡
¿Quiere una excelente herramienta de pruebas de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada y todo en uno para que su equipo de desarrolladores trabaje junto con la máxima productividad?

Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!
botón

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar