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 obtiene 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 primero conviene conocer los campos.

• `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 personalizadas de CSS, divididas en theme, light y dark.
• `css` — reglas de CSS arbitrarias, para cualquier cosa que las variables no puedan expresar.
• `font` — fuentes que necesita el elemento, para que la tipografía no sea un paso manual independiente.
• `categories`, `docs`, `meta` — metadatos para exploradores, instrucciones post-instalación y cualquier dato propio.

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

Aquí hay uno real, activo ahora mismo — el elemento detrás del kit gratuito Ambient Sage, recortado por brevedad. Nada de lo que contiene 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 merecen atención. cssVars.theme contiene la mitad no cromática de un sistema de diseño — radios, sombras, tiempos de movimiento, tipografías — 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 paleta y una inversión. Y docs contiene una instrucción escrita, que la CLI muestra después de la instalación y que un agente de código puede leer.

Instalarlo requiere un solo comando y repinta un proyecto existente en lugar de añadir contenido: cada componente que ya haga 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

   Escriba un archivo de elemento

   Comience con un único registry-item.json. No necesita registry.json, un paso de compilación o un monorepo para que sea útil; un índice es importante una vez que tiene varios elementos y desea un espacio de nombres.

2. 2

   Sírvalo en una URL estable

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

   Copy

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

3. 3

   Configure el tipo de contenido y el CORS correctos

   Sírvalo como application/json. Si algo en un navegador va a solicitarlo —un explorador de registros, una herramienta de previsualización— envíe también encabezados CORS permisivos. Esta es la razón más común por la que un elemento que parece correcto no se instala.

4. 4

   Pruebe con la CLI real

   Instálelo en un proyecto de prueba antes de publicar la URL en cualquier lugar. Un error de esquema aparece aquí en segundos, pero en un informe de errores tardaría semanas.

   Copy

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

Una URL directa es suficiente para un elemento. Una vez que publique varios, un espacio de nombres es preferible: configure el registro una vez en components.json e instale mediante el nombre corto, con múltiples registros uno al lado del otro.

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

registryDependencies permite que un elemento dependa de otros, incluso entre diferentes registros. La CLI resuelve el grafo e instala en orden de dependencia, por lo que un bloque que necesita un botón recibe el botón primero, haya pedido usted el botón o no.

El modo de fallo que debe conocer es el ciclo: dos elementos que se declaran mutuamente como dependencias. Nada se resuelve y el error apunta al paso de resolución en lugar de a su JSON. Si una instalación se cuelga o falla en un elemento que parece correcto, 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 registros, y tiene tres respuestas reales. shadcn mantiene un índice de registros de código abierto de registros disponibles de serie. registry.directory es un explorador independiente que permite navegar y previsualizar elementos antes de instalarlos. Y un número creciente de proyectos individuales —incluido este sitio— publican una URL de elemento estable y simplemente la documentan.

La tercera categoría es fácil de pasar por alto y conviene revisarla 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.

Un agente de código al que se le dan tres colores de marca tiene tres valores y aproximadamente veinticinco indefinidos: estados hover y active, texto atenuado, bordes, ring, destructive, series de gráficos, y cada uno de ellos nuevamente en modo oscuro. Los rellena de forma competente y diferente cada vez, que es exactamente la deriva que un sistema de diseño debe evitar.

Un elemento de registro cierra esa brecha con un solo comando y es portable de una manera que nada más en este espacio lo es: v0 acepta un registro 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 repositorio. Una URL, cuatro herramientas, sin integraciones específicas por herramienta. La parte escrita —qué no hacer nunca, qué variante recibe una acción destructiva— debe ir junto a ello en un DESIGN.md, porque cssVars responde a *qué color* y solo la prosa responde a *qué nunca*.