O registry do shadcn, explicado

Um registry do shadcn é um JSON servido via HTTP. Essa é a ideia central. Não há pacote para publicar, nem runtime, nem serviço para se cadastrar: você hospeda arquivos em URLs, e a CLI do shadcn busca um deles, lê o que ele declara e escreve o resultado no projeto de destino.

É isso que o torna diferente de uma biblioteca de componentes. Uma biblioteca é uma dependência — você a instala, importa dela e o código reside atrás de um número de versão no node_modules. Um registry entrega o código-fonte. Após o shadcn add, os arquivos são seus: no seu repo, no seu diff, editáveis sem a necessidade de um fork. A troca é a habitual — você assume a manutenção e perde as atualizações automáticas — e é nessa troca que toda a abordagem do shadcn é construída.

Você pode publicar um único item e nunca escrever um índice. Essa é a maneira mais rápida e útil de usar um registry, e é para isso que o restante deste guia converge — mas vale a pena conhecer os campos primeiro.

• `name` — o identificador usado nos comandos de instalação e em registryDependencies.
• `type` — que tipo de coisa é esta: registry:ui para um componente, registry:block para um bloco composto de vários arquivos, registry:theme para um conjunto de tokens, registry:style para um estilo inicial completo, além de variantes de hook, lib, page e file.
• `files` — o código-fonte que será escrito, cada um com seu próprio type e caminho target opcional.
• `dependencies` — pacotes npm que o item necessita, instalados automaticamente para você.
• `registryDependencies` — outros itens de registry que este requer, por nome ou URL. A CLI os resolve, e é por isso que a ordem de instalação se organiza sozinha.
• `cssVars` — propriedades customizadas de CSS, divididas em theme, light e dark.
• `css` — regras de CSS arbitrárias, para tudo que as variáveis não conseguem expressar.
• `font` — fontes que o item necessita, para que a tipografia não seja uma etapa manual separada.
• `categories`, `docs`, `meta` — metadados para exploradores, instruções pós-instalação e quaisquer informações personalizadas.

As três que costumam ser ignoradas são cssVars, css e font, porque quase todo tutorial demonstra um componente. Essas três são o que transformam um registry de um mecanismo de distribuição de componentes em um mecanismo de distribuição de design system.

Aqui está um exemplo real, ativo agora — o item por trás do kit gratuito Ambient Sage, resumido por questões de espaço. Nada nele é um 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."
}

Três coisas merecem atenção. cssVars.theme carrega a metade não relacionada a cores de um design system — radii, sombras, timing de animação, tipografias — que é onde a maioria dos "geradores de temas" para e começa a perder o design. light e dark são objetos separados, em vez de uma única paleta e uma inversão. E docs carrega uma instrução escrita, que a CLI exibe após a instalação e que um agente de código pode ler.

Instalá-lo requer um único comando, e ele repinta um projeto existente em vez de apenas adicionar a ele: cada componente que já referencia bg-primary ou text-muted-foreground assume os novos valores sem precisar ser editado.

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

1. 1

   Escreva um arquivo de item

   Comece com um único registry-item.json. Você não precisa de um registry.json, de uma etapa de build ou de um monorepo para ser útil — um índice só importa quando você tem vários itens e deseja um namespace.

2. 2

   Hospede-o em uma URL estável

   Qualquer host estático funciona. O importante é que a URL não mude: ela é o comando de instalação, portanto, acaba colada em READMEs, prompts e configurações de agentes.

   Copy

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

3. 3

   Configure o content type e o CORS corretamente

   Sirva como application/json. Se algo em um navegador for buscá-lo — um explorador de registry, uma ferramenta de preview — envie também headers de CORS permissivos. Este é o motivo mais comum para um item que parece correto não ser instalado.

4. 4

   Teste com a CLI real

   Instale em um projeto de teste antes de publicar a URL em qualquer lugar. Um erro de schema aparece aqui em segundos, mas em um relatório de bug levaria semanas.

   Copy

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

Uma URL bruta serve para um único item. Quando você publica vários, um namespace é melhor: configure o registry uma vez no components.json e instale por nome curto, com múltiplos registries lado a lado.

Registries privados são suportados e a CLI aceita quatro formas de autenticação: um bearer token (OAuth 2.0), uma API key, autenticação básica e um parâmetro de query. Qual você usará é uma decisão de hospedagem, não do shadcn.

registryDependencies permite que um item dependa de outros itens, inclusive entre registries diferentes. A CLI resolve o grafo e instala na ordem de dependência, portanto, um bloco que precisa de um botão recebe o botão primeiro, quer você tenha solicitado ou não.

O modo de falha que você deve conhecer é o ciclo: dois itens que declaram um ao outro. Nada é resolvido, e o erro aponta para a etapa de resolução em vez de para o seu JSON. Se uma instalação travar ou falhar em um item que parece correto, desenhe as setas de dependência no papel antes de depurar qualquer outra coisa.

Esta é a pergunta mais feita e menos respondida sobre registries, e ela tem três respostas reais. O shadcn mantém um índice de registry open-source de registries disponíveis nativamente. O registry.directory é um explorador independente que permite navegar e visualizar itens antes de instalá-los. E um número crescente de projetos individuais — incluindo este site — publica uma URL de item estável e simplesmente a documenta.

A terceira categoria é fácil de ignorar e vale a pena checar primeiro: se um projeto que você já gosta possui um tema ou um conjunto de componentes que você deseja, procure por um caminho /r/ antes de assumir que terá que copiar o CSS manualmente.

Um agente de código que recebe três cores de marca tem três valores e aproximadamente vinte e cinco indefinidos: estados de hover e active, texto muted, bordas, ring, destructive, séries de gráficos e cada um desses novamente no modo dark. Ele os preenche de forma competente, mas diferente a cada vez, que é exatamente o desvio (drift) que um design system deve evitar.

Um item de registry fecha essa lacuna em um único comando, e é portátil de uma forma que nada mais neste espaço é: o v0 aceita um registry como fonte de design system, o Bolt pode instalar um a partir de seu terminal no navegador, e o Cursor ou Claude Code podem executar o mesmo comando no seu repo. Uma URL, quatro ferramentas, sem integração por ferramenta. A parte escrita — o que nunca fazer, qual variante uma ação destrutiva recebe — deve estar ao lado disso em um DESIGN.md, porque cssVars responde *qual cor* e apenas a prosa responde *o que nunca*.