Registry — Shadwire

O registry do Shadwire está publicado em shadwire.edumoraes.dev.br/r. Ele tem um índice com o catálogo e um arquivo por item, que traz o código completo de cada um dos arquivos do item.

URL	Conteúdo
`/r/index.json`	O catálogo (nome, título, descrição, quando usar) e o `base`: os arquivos compartilhados e as gems que o init instala.
`/r/{nome}.json`	Um componente: os metadados, os outros itens de que ele depende, a API e os arquivos com o conteúdo de cada um.
`/r/llms.txt`	O mesmo catálogo em texto simples, para agentes.
`/r/llms-full.txt`	A API completa de cada componente, em texto simples.

curl -s https://shadwire.edumoraes.dev.br/r/index.json | jq '.items | length'
curl -s https://shadwire.edumoraes.dev.br/r/button.json | jq '.api.components[0].variants'

index.json

É o arquivo que list e search leem, e de onde o init tira os arquivos base.

{
  "name": "shadwire",
  "version": "0.2.0",
  "items": [
    {
      "name": "button",
      "type": "component",
      "title": "Button",

{
  "name": "shadwire",
  "version": "0.2.0",
  "items": [
    {
      "name": "button",
      "type": "component",
      "title": "Button",
      "description": "Displays a button or a link styled as a button.",
      "whenToUse": "Any clickable action. Use tag: :a for a link that looks like a button…"
    }
  ],
  "base": {
    "files": [{ "target": "app/components/ui_component.rb", "type": "component", "content": "…" }],
    "gems": ["view_component", "lucide-rails"],
    "tailwind": { "version": "4", "css": "shadwire.css" }
  }
}

Um item

Cada item traz tudo o que é preciso para instalá-lo numa única requisição, inclusive o conteúdo dos arquivos. registryDependencies já inclui as dependências das dependências, então a CLI não precisa buscá-las uma a uma.

{
  "name": "button",
  "type": "component",
  "title": "Button",
  "description": "Displays a button or a link styled as a button.",
  "whenToUse": "Any clickable action…",
  "usage": ["<%= ui_button(variant: :outline, size: :sm) { \"Save\" } %>"],
  "gems": [],

{
  "name": "button",
  "type": "component",
  "title": "Button",
  "description": "Displays a button or a link styled as a button.",
  "whenToUse": "Any clickable action…",
  "usage": ["<%= ui_button(variant: :outline, size: :sm) { \"Save\" } %>"],
  "gems": [],
  "importmap": [],
  "registryDependencies": ["icon"],
  "requiresStimulus": false,
  "api": {
    "components": [
      {
        "class": "Ui::ButtonComponent",
        "helper": "ui_button",
        "root": true,
        "variants": ["default", "destructive", "outline", "secondary", "ghost", "link"],
        "sizes": ["default", "sm", "lg", "icon"],
        "props": [{ "name": "tag", "default": ":button" }]
      }
    ]
  },
  "files": [
    {
      "target": "app/components/ui/button_component.rb",
      "type": "component",
      "content": "# frozen_string_literal: true\n\nmodule Ui\n  class ButtonComponent…"
    }
  ]
}

Campo	O que é
`whenToUse`	Uma frase dizendo quando usar este componente e quais parecidos considerar. A busca procura nesse texto.
`usage`	Trechos de ERB para os usos mais comuns.
`registryDependencies`	Os outros itens que são instalados junto, incluindo as dependências indiretas.
`requiresStimulus`	Verdadeiro quando o item instala um controller em app/javascript/.
`api.components[]`	Lido do código-fonte: classe, helper, variantes, tamanhos, argumentos e atributos.
`files[]`	Cada arquivo como `{ target, type, content }`. Os caminhos dentro do repositório do Shadwire ficam de fora.

Como ele é construído

Tudo parte do registry/registry.json no repositório do Shadwire, que lista os arquivos de cada item como pares source → target. O bin/build_registry transforma isso no registry publicado: copia o conteúdo de cada arquivo e lê a API do código-fonte:

bin/build_registry            # registry/registry.json → build/r/{name}.json + index.json
ls build/r | head

A saída vai para build/, que é gerada e não deve ser editada à mão. O CI a reconstrói a cada push na main, quando publica este site.

Hospedando o seu

Como são arquivos estáticos, dá para hospedar em qualquer lugar: um bucket, o GitHub Pages, um diretório atrás de um servidor web. Aponte a CLI para lá com --registry, ou passe a flag no init para salvá-la no shadwire.json.

URLs file:// também funcionam, o que ajuda a testar um registry que você gerou localmente:

bin/build_registry
bin/shadwire add button --registry "file://$PWD/build/r"

A URL do registry fica gravada no app do usuário

O shadwire.json guarda a URL usada quando o init rodou. Os apps que já instalaram a partir do seu registry continuam usando esse endereço, então, se você mudar o registry de lugar, deixe um redirecionamento na URL antiga.