Registry — Shadwire

Shadwire's registry is published at shadwire.edumoraes.dev.br/r. It has an index with the catalog, and one file per item that contains the full source of each of the item's files.

URL	Contents
`/r/index.json`	The catalog (name, title, description, when to use) and `base`: the shared files and gems that init installs.
`/r/{name}.json`	One component: its metadata, the other items it depends on, its API, and its files with their contents.
`/r/llms.txt`	The same catalog in plain text, for agents.
`/r/llms-full.txt`	Every component's full API in plain text.

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

list and search read this file, and init gets the base files from it.

{
  "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" }
  }
}

One item

Each item has everything needed to install it in a single request, file contents included. registryDependencies already includes the dependencies of dependencies, so the CLI does not have to look them up one by one.

{
  "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…"
    }
  ]
}

Field	What it is
`whenToUse`	A sentence on when to use this component and which similar ones to consider. Search matches against this text.
`usage`	ERB snippets for the most common uses.
`registryDependencies`	The other items that get installed with it, including indirect dependencies.
`requiresStimulus`	True when the item installs a controller under app/javascript/.
`api.components[]`	Read from the source code: class, helper, variants, sizes, arguments and attributes.
`files[]`	Each file as `{ target, type, content }`. Paths inside the Shadwire repository are left out.

How it is built

It starts from registry/registry.json in the Shadwire repository, which lists each item's files as source → target pairs. bin/build_registry turns that into the published registry: it copies in each file's contents and reads the API from the source:

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

The output goes to build/, which is generated and should not be edited by hand. CI rebuilds it on every push to main, when it deploys this site.

Serving your own

These are static files, so you can host them anywhere: a storage bucket, GitHub Pages, a directory behind a web server. Point the CLI at it with --registry, or pass the flag to init to save it in shadwire.json.

file:// URLs work too, which is handy for testing a registry you built locally:

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

The registry URL is written into the user's app

shadwire.json keeps the URL that was used when init ran. Apps that already installed from you keep using that address, so if you move a registry, leave a redirect at the old URL.