The shadcn registry, explained

A shadcn registry is JSON served over HTTP. That is the whole idea. There is no package to publish, no runtime, no service to sign up for: you host files at URLs, and the shadcn CLI fetches one, reads what it declares, and writes the result into the consuming project.

That is what makes it different from a component library. A library is a dependency — you install it, you import from it, and its code lives behind a version number in node_modules. A registry hands you source. After shadcn add, the files are yours: in your repo, in your diff, editable without a fork. The trade is the usual one — you own the maintenance and you lose automatic updates — and it is the trade the whole shadcn approach is built on.

You can publish a single item and never write an index at all. That is the fastest useful thing you can do with a registry, and it is what the rest of this guide builds toward — but the fields are worth knowing first.

• `name` — the identifier used in install commands and in registryDependencies.
• `type` — what kind of thing this is: registry:ui for a component, registry:block for a composed multi-file block, registry:theme for a token set, registry:style for a whole starting style, plus hook, lib, page and file variants.
• `files` — the source that gets written, each with its own type and optional target path.
• `dependencies` — npm packages the item needs, installed for you.
• `registryDependencies` — other registry items this one requires, by name or URL. The CLI resolves them, which is why installation order sorts itself out.
• `cssVars` — CSS custom properties, split into theme, light and dark.
• `css` — arbitrary CSS rules, for anything variables cannot express.
• `font` — fonts the item needs, so type is not a separate manual step.
• `categories`, `docs`, `meta` — metadata for explorers, post-install instructions, and anything of your own.

The three that get overlooked are cssVars, css and font, because almost every tutorial demonstrates a component. Those three are what turn a registry from a component-distribution mechanism into a design-system-distribution mechanism.

Here is a real one, live right now — the item behind the free Ambient Sage kit, trimmed for length. Nothing in it is a component:

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

Three things are worth noticing. cssVars.theme carries the non-colour half of a design system — radii, shadows, motion timing, type faces — which is where most "theme generators" stop and start losing the design. light and dark are separate objects rather than one palette and an inversion. And docs carries a written instruction, which the CLI surfaces after install and a coding agent can read.

Installing it is one command, and it repaints an existing project rather than adding to it: every component already referencing bg-primary or text-muted-foreground picks up the new values without being edited.

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

1. 1

   Write one item file

   Start with a single registry-item.json. You do not need registry.json, a build step, or a monorepo to be useful — an index matters once you have several items and want a namespace.

2. 2

   Serve it at a stable URL

   Any static host works. What matters is that the URL does not move: it is the install command, so it ends up pasted in READMEs, prompts and agent configs.

   Copy

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

3. 3

   Set the right content type and CORS

   Serve application/json. If anything in a browser will fetch it — a registry explorer, a preview tool — send permissive CORS headers too. This is the most common reason an item that looks correct will not install.

4. 4

   Test with the real CLI

   Install into a scratch project before you publish the URL anywhere. A schema mistake surfaces here in seconds and in a bug report in weeks.

   Copy

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

A raw URL is fine for one item. Once you publish several, a namespace is nicer: configure the registry once in components.json and install by short name, with multiple registries side by side.

Private registries are supported and the CLI accepts four authentication shapes: a bearer token (OAuth 2.0), an API key, basic authentication, and a query parameter. Which you use is a hosting decision, not a shadcn one.

registryDependencies lets an item depend on other items, including across registries. The CLI resolves the graph and installs in dependency order, so a block that needs a button gets the button first, whether or not you asked for it.

The failure mode to know about is a cycle: two items that each declare the other. Nothing resolves, and the error points at the resolution step rather than at your JSON. If an install hangs or fails on an item that looks fine, draw the dependency arrows on paper before debugging anything else.

This is the most-asked and least-answered question about registries, and it has three real answers. shadcn maintains an open-source registry index of registries available out of the box. registry.directory is an independent explorer that lets you browse and preview items before installing. And a growing number of individual projects — this site included — publish a stable item URL and simply document it.

The third category is easy to overlook and worth checking first: if a project you already like has a theme or a component set you want, look for a /r/ path before assuming you have to copy CSS by hand.

A coding agent given three brand colours has three values and roughly twenty-five undefined ones: hover and active states, muted text, borders, ring, destructive, chart series, and every one of those again in dark mode. It fills them competently and differently each time, which is exactly the drift a design system is supposed to prevent.

A registry item closes that gap in one command, and it is portable in a way nothing else in this space is: v0 accepts a registry as a design-system source, Bolt can install one from its in-browser terminal, and Cursor or Claude Code can run the same command in your repo. One URL, four tools, no per-tool integration. The written half — what never to do, which variant a destructive action gets — belongs alongside it in a DESIGN.md, because cssVars answers *what colour* and only prose answers *what never*.