El registro de shadcn, explicado

Un registro de shadcn es JSON servido a través de HTTP. Esa es la idea central. No hay paquetes que publicar, ni runtime, ni servicios en los que registrarse: usted aloja archivos en URLs, y el CLI de shadcn descarga uno, lee lo que declara y escribe el resultado en el proyecto de destino.

Eso es lo que lo diferencia de una librería de componentes. Una librería es una dependencia: se instala, se importa desde ella y su código reside tras un número de versión en node_modules. Un registro le entrega el código fuente. Después de ejecutar shadcn add, los archivos son suyos: están en su repositorio, en su diff y son editables sin necesidad de un fork. El intercambio es el habitual (usted se encarga del mantenimiento y pierde las actualizaciones automáticas), y es el intercambio sobre el cual se construye todo el enfoque de shadcn.

Puede publicar un único elemento y no escribir nunca un índice. Es lo más rápido y útil que puede hacer con un registro, y es hacia donde se dirige el resto de esta guía, pero conviene conocer los campos primero.

• `name`: el identificador utilizado en los comandos de instalación y en registryDependencies.
• `type`: qué tipo de elemento es: registry:ui para un componente, registry:block para un bloque compuesto de varios archivos, registry:theme para un conjunto de design tokens, registry:style para un estilo inicial completo, además de variantes de hook, lib, page y file.
• `files`: el código fuente que se escribe, cada uno con su propio type y una ruta target opcional.
• `dependencies`: paquetes de npm que el elemento necesita, instalados automáticamente.
• `registryDependencies`: otros elementos del registro que este requiere, por nombre o URL. El CLI los resuelve, razón por la cual el orden de instalación se gestiona solo.
• `cssVars`: propiedades CSS personalizadas, divididas en theme, light y dark.
• `css`: reglas CSS arbitrarias, para cualquier cosa que las variables no puedan expresar.
• `font`: fuentes que el item necesita, para que el tipo no sea un paso manual independiente.
• `categories`, `docs`, `meta`: metadatos para exploradores, instrucciones post-instalación y cualquier otra cosa propia.

Las tres que se pasan por alto son cssVars, css y font, porque casi todos los tutoriales demuestran un componente. Esas tres son las que convierten un registry de un mecanismo de distribución de componentes en un mecanismo de distribución de sistemas de diseño.

Aquí hay uno real, disponible ahora mismo: el item detrás del kit gratuito Ambient Sage, recortado para ahorrar espacio. Nada en él es un componente:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "ambient-sage",
  "type": "registry:theme",
  "title": "Ambient Sage",
  "description": "A warm-sage neutral-surface kit with a single vivid yellow accent.",
  "categories": ["minimal", "warm-neutral", "flat", "calm", "yellow-accent"],
  "cssVars": {
    "theme": {
      "font-heading": "'Plus Jakarta Sans', sans-serif",
      "font-mono": "'JetBrains Mono', monospace",
      "radius-button": "0.75rem",
      "radius-card": "1.25rem",
      "shadow-sm": "none",
      "duration": "180ms",
      "ease": "cubic-bezier(0.4,0,0.2,1)"
    },
    "light": {
      "background": "72 19% 95%",
      "foreground": "84 10% 10%",
      "card": "70 11% 89%",
      "primary": "54 98% 66%"
    },
    "dark": {
      "background": "84 10% 10%",
      "foreground": "68 13% 88%",
      "card": "80 9% 14%"
    }
  },
  "font": { "heading": "Plus Jakarta Sans", "mono": "JetBrains Mono" },
  "docs": "Use the semantic tokens; do not add a second accent."
}

Hay tres cosas que vale la pena notar. cssVars.theme transporta la mitad no relacionada con el color de un sistema de diseño (radii, sombras, tiempos de movimiento, tipos de letra), que es donde la mayoría de los "generadores de temas" se detienen y empiezan a perder el diseño. light y dark son objetos separados en lugar de una sola paleta y su inversión. Y docs transporta una instrucción escrita, que la CLI muestra tras la instalación y que un agente de código puede leer.

Instalarlo es un solo comando, y repinta un proyecto existente en lugar de añadir elementos a él: cada componente que ya referencia a bg-primary o text-muted-foreground adopta los nuevos valores sin necesidad de ser editado.

npx shadcn add https://identityforge.io/r/ambient-sage.json

1. 1

   Escribir un único archivo de item

   Comience con un único registry-item.json. No necesita registry.json, un paso de compilación ni un monorepo para que sea útil. Un índice importa una vez que tenga varios items y quiera un espacio de nombres.

2. 2

   Servirlo en una URL estable

   Cualquier host estático funciona. Lo que importa es que la URL no cambie: es el comando de instalación, por lo que acaba pegada en READMEs, prompts y configuraciones de agentes.

   Copy

   https://identityforge.io/r/<slug>.json

3. 3

   Establecer el content type y CORS correctos

   Sirva application/json. Si algo en un navegador va a realizar una petición (un explorador de registry, una herramienta de previsualización), envíe también cabeceras CORS permisivas. Esta es la razón más común por la que un item que parece correcto no se instala.

4. 4

   Probar con la CLI real

   Instálelo en un proyecto de prueba antes de publicar la URL en cualquier lugar. Un error de esquema se detecta aquí en segundos y en un reporte de error en semanas.

   Copy

   npx shadcn add https://example.com/r/thing.json

Una URL pura está bien para un solo item. Una vez que publique varios, un namespace es más conveniente: configure el registry una vez en components.json e instale mediante el nombre corto, con múltiples registries funcionando en paralelo.

Los registries privados son compatibles y la CLI acepta cuatro formas de autenticación: un bearer token (OAuth 2.0), una API key, autenticación básica y un parámetro de consulta. Cuál utilice es una decisión de hosting, no de shadcn.

registryDependencies permite que un item dependa de otros items, incluso entre diferentes registries. La CLI resuelve el grafo e instala en orden de dependencia, por lo que un bloque que necesite un botón obtiene el botón primero, le haya pedido usted el botón o no.

El modo de fallo que debe conocer es un ciclo: dos items que declaran el uno al otro. Nada se resuelve y el error apunta al paso de resolución en lugar de a su JSON. Si una instalación se queda colgada o falla en un item que parece estar bien, dibuje las flechas de dependencia en papel antes de depurar cualquier otra cosa.

Esta es la pregunta más frecuente y menos respondida sobre los registries, y tiene tres respuestas reales. shadcn mantiene un índice de registries de código abierto de registries disponibles de serie. registry.directory es un explorador independiente que le permite navegar y previsualizar items antes de instalarlos. Y un número creciente de proyectos individuales, incluido este sitio, publican una URL de item estable y simplemente la documentan.

La tercera categoría es fácil de pasar por alto y merece la pena consultarla primero: si un proyecto que ya le gusta tiene un tema o un conjunto de componentes que desea, busque una ruta /r/ antes de asumir que tiene que copiar el CSS a mano.

A un agente de código al que se le dan tres colores de marca se le dan tres valores y aproximadamente veinticinco indefinidos: estados hover y active, texto atenuado, bordes, ring, destructivo, series de gráficos, y cada uno de esos de nuevo en modo oscuro. Los completa de forma competente y diferente cada vez, lo cual es exactamente la deriva que un sistema de diseño debe prevenir.

Un item de registry cierra esa brecha con un solo comando, y es portátil de una forma en la que nada más en este espacio lo es: v0 acepta un registry como fuente de sistema de diseño, Bolt puede instalar uno desde su terminal en el navegador, y Cursor o Claude Code pueden ejecutar el mismo comando en su repo. Una URL, cuatro herramientas, sin integración por herramienta. La parte escrita (qué no hacer nunca, qué variante recibe una acción destructiva) pertenece junto a él en un DESIGN.md, porque cssVars responde a *qué color* y solo la prosa responde a *qué nunca*.