@lexydesign/create-app

CLI oficial de Lexy para generar proyectos React + Vite + TypeScript con arquitectura estandarizada, addons opcionales (Tailwind, shadcn, React Router…), el sistema de diseño Lexy y un registry de componentes listos para copiar.

mkdir mi-app && cd mi-app
npx @lexydesign/create-app

Contenido

• ¿Qué hace?
• Inicio rápido
• Crear un proyecto (create)
  • Modo interactivo
  • Modo automatizado (headless)
• Arquitecturas
• Addons
• El archivo .lexy
• Agregar elementos (add)
• Catálogo de componentes
• Sistema de diseño (tema)
• Infraestructura de IA del template
• Desarrollo del CLI (contribuir a este repo)
  • Estructura del repositorio
  • Storybook
  • Probar el CLI en local
  • Publicar una versión

¿Qué hace?

El CLI cubre tres funciones:

| Función | Comando | Resultado | |---|---|---| | Crear un proyecto | create-lexy | Scaffold completo de React + Vite + TS con la arquitectura y addons elegidos. | | Agregar elementos | create-lexy add <Nombre> --component | Copia un componente, hook o servicio del registry al proyecto. | | Diseñar con tokens | (incluido en el scaffold) | Tema Lexy unificado + catálogo de componentes documentado en Storybook. |

Inicio rápido

[!IMPORTANT] El scaffold se genera en el directorio actual (in-place), no en una subcarpeta. Crea una carpeta vacía, entra en ella y ejecuta el comando ahí. Si el directorio ya contiene package.json, src, index.html o .lexy, el CLI aborta para no sobrescribir un proyecto existente.

mkdir mi-app && cd mi-app
npx @lexydesign/create-app

También funcionan los atajos create de cada gestor, que resuelven internamente al mismo paquete:

npm create @lexydesign/app
# o
pnpm create @lexydesign/app

El nombre publicado es @lexydesign/create-app. El atajo create @lexydesign/app es azúcar que npm/pnpm expanden a ese paquete. Si ves una versión vieja en caché, fuerza la última con npx @lexydesign/create-app@latest.

Al terminar, el proyecto queda listo en el directorio actual. Siguiente paso:

pnpm dev

Crear un proyecto (create)

create es el comando por defecto: create-lexy, create-lexy create y create-lexy init son equivalentes.

Modo interactivo

Te guía por nombre, configuración y addons:

create-lexy

Ofrece dos caminos:

• Configuración recomendada — arquitectura feature + todos los addons (Tailwind, React Router, Lucide, shadcn, React Compiler, React Doctor, GitHub Actions y Husky).
• Personalizar — eliges arquitectura y addons manualmente.

Modo automatizado (headless)

Útil para scripts y agentes. Se activa solo cuando pasas el nombre del proyecto y --type a la vez:

create-lexy create mi-app --type feature --addons tailwind,shadcn,react-router

| Argumento / opción | Descripción | |---|---| | mi-app | Nombre del proyecto (queda en package.json). No crea una carpeta con ese nombre; el scaffold es in-place. | | -t, --type <arch> | Arquitectura: feature o layer. Obligatorio en headless; si lo omites, el CLI entra en modo interactivo. | | -a, --addons <lista> | Addons separados por coma. Los valores inválidos se ignoran. |

Seleccionar shadcn añade automáticamente tailwind y lucide-react.

Arquitecturas

El CLI genera una de dos estructuras de carpetas según --type:

feature — recomendada para apps escalables

src/
├── app/                  # Entrada, layout y router
├── features/             # Módulos por funcionalidad
└── shared/
    ├── assets/
    ├── components/
    │   └── base/         # ← destino de `add --component`
    ├── hooks/            # ← destino de `add --hook`
    ├── services/         # ← destino de `add --service`
    ├── lib/              # cn.ts y utilidades
    └── types/

layer — clásica, por capas

src/
├── assets/
├── components/
│   └── base/             # ← destino de `add --component`
├── hooks/                # ← destino de `add --hook`
├── services/             # ← destino de `add --service`
├── lib/                  # cn.ts y utilidades
├── types/
├── views/
└── stores/

Las rutas concretas de cada arquitectura quedan registradas en .lexy y son las que usa add para saber dónde copiar.

Addons

Todos son opcionales y se instalan solo si los seleccionas (opt-in), manteniendo el bootstrap mínimo.

| Addon | Qué configura | |---|---| | tailwind | TailwindCSS v4 vía @tailwindcss/vite, helper cn, e index.css con el tema Lexy. | | shadcn | components.json (estilo new-york). Implica tailwind + lucide-react. | | lucide-react | Librería de íconos. | | react-router | react-router-dom + Router.tsx base y carpeta de middlewares. | | react-compiler | Cambia a @vitejs/plugin-react y activa babel-plugin-react-compiler. | | react-doctor | Script doctor de análisis en package.json. | | github-actions | Workflow ci.yml (install → lint → build). | | husky | git init + Husky + lint-staged con hook pre-commit. |

El archivo .lexy

Cada proyecto generado incluye un .lexy en la raíz: es el manifiesto que el comando add lee para saber arquitectura y rutas de destino.

{
  "version": "1.0.0",
  "generatedAt": "2026-06-08T00:00:00.000Z",
  "architecture": "feature",
  "addons": ["tailwind", "shadcn", "react-router"],
  "paths": {
    "components": "src/shared/components/base",
    "hooks": "src/shared/hooks",
    "services": "src/shared/services",
    "lib": "src/shared/lib",
    "views": "src/features"
  }
}

Agregar elementos (add)

Copia un elemento del registry al proyecto actual. Debe ejecutarse en la raíz de un proyecto generado (donde está el .lexy).

create-lexy add Button --component     # componente
create-lexy add useAuth  --hook        # hook
create-lexy add authApi  --service     # servicio

| Opción | Destino (según .lexy) | |---|---| | -c, --component | paths.components | | -k, --hook | paths.hooks | | -s, --service | paths.services |

Al agregar un componente, el CLI automáticamente:

• Crea cn.ts en paths.lib si no existe.
• Instala las dependencias base (clsx, tailwind-merge).
• Instala class-variance-authority si el componente lo usa.
• Instala las dependencias externas específicas (Radix, cmdk, lucide-react…) solo de los componentes que las importan.
• Resuelve y copia dependencias internas transitivas. Por ejemplo:
  • Shell → copia Sidebar, HeaderBar y Button.
  • Combobox → copia Popover, Command y Button.
  • Sidebar → copia Sheet, Button, Input, Separator, Skeleton y Tooltip.
• Copia los assets asociados. Por ejemplo, Logo copia assets/logo.

Catálogo de componentes

Los componentes viven en templates/elements/components y están documentados en Storybook (ver Storybook). Organizados por categoría:

| Categoría | Componentes | |---|---| | Navegación | AppSidebar, Breadcrumb, HeaderBar, Menubar, NavigationMenu, Shell | | Formularios | Button, Checkbox, Combobox, Input, Label, RadioGroup, Searchbox, Select, Slider, Switch, Textarea | | Feedback | Badge, CounterBadge, Progress, Skeleton, StatusDot, Toast, Tooltip | | Overlays | Command, Dialog, DropdownMenu, Popover | | Datos | Accordion, Card, Separator, Snippet, Table, Tabs, Tag, Tree | | Identidad | Avatar, FeatureCard, Logo, ProfileCard |

Shell es un componente compuesto: HeaderBar a ancho completo con el trigger de la sidebar, y la sidebar a todo el alto bajo el header.

[!TIP] AppSidebar es la barra de navegación. Recibe groups, user, logo y logoIcon como datos y compone la sidebar correctamente (data-driven), lo que evita errores al generar la UI con un agente de IA. Sidebar y Sheet son primitivas internas que AppSidebar usa por debajo (se copian como dependencia); recurre a ellas solo para casos a medida. Al agregar AppSidebar con add, se copia junto a él un AppSidebar.md con la guía de uso para que un agente lo consulte en el proyecto.

Sistema de diseño (tema)

La fuente única de verdad del tema es templates/lexy-theme.css. Lo consumen tanto Storybook como el proyecto generado, así que cualquier cambio de tokens se hace ahí.

• Tipografía: Noto Sans (variable, auto-hospedada, SIL OFL) como fuente única. El woff2 vive en public/fonts (Storybook) y se propaga a templates/base/public/fonts (proyecto generado).
• Color: tokens semánticos con nomenclatura shadcn/Tailwind (bg-primary, text-muted-foreground…) y valores alineados con LexyDesign. Cada token trae su contraste *-foreground; los fondos de estado se aplican por opacidad (bg-success/10…).
• Escala tipográfica: rampa text-xs … text-5xl, con tracking nativo en cuerpo y negativo progresivo en titulares.
• Espaciado: tokens semánticos (stack-sm/md/lg, gutter, section-gap, page-bottom, margin-mobile/desktop, container-max).

Las stories Estilo/Color y Estilo/Tipografía documentan estos tokens de forma visual.

Infraestructura de IA del template

Los proyectos generados incluyen una infraestructura de IA removible que guía a agentes (Claude Code, Copilot, etc.) para implementar interfaces usando el registry y el sistema de diseño.

| Archivo | Propósito | |---|---| | AGENTS.md | Entrada principal para agentes. | | CLAUDE.md | Entrada automática para Claude Code. | | .github/copilot-instructions.md | Entrada automática para GitHub Copilot. | | ai/README.md | Índice de la infraestructura. | | ai/IMPLEMENTATION-PROTOCOL.md | Protocolo obligatorio para implementar interfaces. | | ai/lexy-ai-manifest.json | Índice JSON de comandos, rutas, addons y componentes. | | ai/TECHNICAL-USAGE.md | Guía técnica para usar el template e importar componentes. | | ai/pautas/diseno-cliente.md | Pautas para interfaces de cliente. | | ai/pautas/diseno-crm-lexy.md | Pautas para CRM e interfaces internas. | | ai/pautas/sistema-visual.md | Densidad, espaciado, estados, tipografía y motion. | | ai/pautas/recetas-layout.md | Composiciones canónicas en código. | | ai/pautas/buenas-practicas.md | Elección de componentes, estados y anti-patrones. | | ai/pautas/arquitectura-informacion-ux.md | Jerarquía, progressive disclosure, carga visual. | | ai/pautas/ux-writing.md | UX writing y microcopy. | | ai/PRODUCTION-CLEANUP.md | Comando para retirar todo antes de producción. |

Para eliminar la infraestructura antes de producción:

rm -rf AGENTS.md CLAUDE.md .claude .github/copilot-instructions.md ai

Desarrollo del CLI (contribuir a este repo)

Esta sección es para quien trabaja en el propio CLI, no para quien lo usa.

Estructura del repositorio

.
├── src/                      # Código del CLI (TypeScript)
│   ├── index.ts              # Entrada y definición de comandos (commander)
│   ├── commands/add.ts       # Comando `add` + registry de dependencias
│   ├── prompts/              # Prompts interactivos (@clack/prompts)
│   ├── services/             # scaffold.ts e installAddons.ts
│   └── types/
├── templates/
│   ├── base/                 # Plantilla del proyecto generado
│   ├── elements/components/  # Registry de componentes copiables
│   └── lexy-theme.css        # Tema (fuente única de verdad)
├── stories/                  # Storybook (consume templates/elements)
├── scripts/release.sh        # Publicación a npm
└── dist/                     # Build del CLI (tsup) — se publica

El paquete publicado solo incluye dist y templates (campo files). El código de src, stories y scripts no se publica.

Storybook

Storybook vive en la raíz y permite ver y trabajar los componentes de templates/elements/components sin tocar la plantilla ni un proyecto generado.

pnpm install
pnpm storybook          # http://localhost:6006
pnpm build-storybook    # versión estática en storybook-static/ (ignorada por Git)

Detalles:

• Framework @storybook/react-vite 8.6.18.
• Historias en stories/**/*.stories.tsx.
• Alias @ → ./src; CSS base en src/styles/storybook.css; tema compartido en templates/lexy-theme.css.

Probar el CLI en local

1. Construir y linkear globalmente este CLI (en este repo):

   pnpm run local:setup

2. Enlazarlo en tu proyecto de prueba:

   pnpm link --global @lexydesign/create-app

3. Probarlo:

   create-lexy

Tras cada cambio en el CLI, reconstruye y vuelve a linkear:

pnpm run local:refresh

Para limpiar los enlaces — en este repo pnpm run local:unlink; en el proyecto de prueba pnpm unlink @lexydesign/create-app.

Publicar una versión

La publicación está automatizada en scripts/release.sh (atajo pnpm release). El script:

1. Carga NPM_TOKEN desde .env (token de automatización de npm, salta el 2FA).
2. Sube la versión en package.json según el tipo de bump.
3. Verifica que la versión resultante no coincida con la ya publicada (aborta si sí).
4. Construye el dist.
5. Publica con un .npmrc temporal, sin tocar tu ~/.npmrc.

pnpm release            # bump patch (1.0.x → 1.0.x+1) y publica
pnpm release minor      # bump minor
pnpm release major      # bump major
pnpm release --no-bump  # publica la versión ya escrita en package.json

[!IMPORTANT] Copia .env.example a .env y coloca tu NPM_TOKEN. El .env está en .gitignore y nunca se incluye en el paquete.