What is a shadcn registry, and how do you install from one?

A shadcn registry is a set of JSON files, one per component, block or theme, that the shadcn CLI installs into your project as source code. Install by name, URL, GitHub repo or @namespace, with a token for private ones. mebius.design’s @mebius registry serves 19 paid kits and free items.

7 min read · Updated Nov 19, 2026 · React + Tailwind

What is a shadcn registry?

Checked in shadcn’s registry docs on 19 Nov 2026.

A shadcn registry is how code is shared through the shadcn CLI. shadcn’s registry docs describe it as a way to distribute components, hooks, pages, config, rules and other files to any project, and note that it works with any framework, not only React.

A shadcn registry has an index, registry.json, that lists its items, and one JSON file per item. Each item file carries the source code and what that code needs: npm packages, other registry items and CSS variables. When you run shadcn add, the CLI fetches the item’s JSON and writes its files into your project. The code is yours to edit.

This guide covers the reader’s side: what a shadcn registry holds and how to install from one. How mebius.design builds its registry from a Figma file is in From Figma to React with a shadcn registry.

What is inside a shadcn registry item?

The fields of registry-item.json, checked on 19 Nov 2026.

Every shadcn registry item follows the registry-item.json schema. The fields that matter when you install:

To read an item before you install it, npx shadcn@latest view prints its files. For a mebius.design starter chart:

Terminal
npx shadcn@latest view @mebius/charts-ethereum

How do you install from a shadcn registry?

Four ways to point the shadcn CLI at an item.

The shadcn CLI’s add command takes an item in four forms. Run npx shadcn@latest init first if the project has no components.json.

Terminal
# shadcn/ui's own registry, by name
npx shadcn@latest add button

# a namespaced registry, here mebius.design's
npx shadcn@latest add @mebius/charts-ethereum

# any registry, by the item's URL
npx shadcn@latest add https://www.mebius.design/r/charts-ethereum.json

# a GitHub repository with a registry.json, pinned to a tag
npx shadcn@latest add acme/ui/button#v1.2.0

Each form also installs the item’s dependencies, from whichever registry they live in. GitHub registries need no server: a repository with a valid registry.json at its root is enough. The CLI uses the default branch unless you pin a tag, branch or commit after #.

Every install copies third-party code into your project, so review it first, as shadcn’s directory advises.

How do namespaces work in components.json?

Checked in shadcn’s namespace docs on 19 Nov 2026.

A shadcn namespace maps a prefix such as @acme to a URL template. You add it under registries in components.json, and shadcn’s namespace docs allow two forms:

The public @mebius entry uses the string form, as in the open starter repository:

components.json
{
  "registries": {
    "@mebius": "https://www.mebius.design/r/{name}.json"
  }
}

Registries in shadcn’s directory work without an entry. You add one when a registry isn’t listed, or when it needs a header.

How do private shadcn registries with a token work?

Bearer tokens, as the @mebius registry uses them.

shadcn’s authentication docs call a bearer token in the Authorization header the most common approach. Other private registries use an API key header or a token query parameter. The token lives in .env.local, never in components.json, and the docs recommend HTTPS, rate limits, token rotation and access logs on the server side.

For mebius.design, create a token in Settings › Tokens (a free account works), then use the object form and put the token in .env.local:

components.json
{
  "registries": {
    "@mebius": {
      "url": "https://www.mebius.design/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${MEBIUS_TOKEN}"
      }
    }
  }
}
.env.local
MEBIUS_TOKEN=mbs_your_token

A mebius.design token reads the kits its account owns at that moment, so a refund ends access. The @mebius registry answers with a message the CLI prints:

With the token set, npx shadcn@latest search @mebius lists what that account can install. Every command and error is in the shadcn MCP and CLI guide.

What is the shadcn registry directory, and how does a registry get listed?

593 registries when we checked on 19 Nov 2026.

shadcn’s registry directory listed 593 community registries on 19 Nov 2026. They are built into the CLI, so npx shadcn add @<registry>/<component> works with no setup. Third-party developers maintain them.

To get a registry into the shadcn directory, the registry index docs ask for a registry that is:

You add an entry to apps/v4/registry/directory.json in the shadcn-ui/ui repository, run pnpm validate:registries and open a pull request, which the shadcn team reviews. mebius.design’s @mebius registry joined the directory this way in pull request #12763, merged on 19 Nov 2026 with four other community registries.

What does mebius.design’s @mebius registry include?

Counted from the live catalog on 19 Nov 2026.

mebius.design’s @mebius registry serves three tiers from one namespace. The open starter needs no account, the free charts and forms need a free account, and each paid kit needs a purchase. Every item is designed in Figma first.

The @mebius registry at a glance
Namespace@mebius, served from https://www.mebius.design/r/{name}.json
shadcn directoryListed since 19 Nov 2026 (pull request #12763)
Open starter20 charts and forms, MIT, no account or token (source on GitHub)
Free with an account62 charts and 128 forms, each with its Figma file
Paid kits19 kits with React code: 2,046 components and 1,061 blocks
AuthAuthorization: Bearer ${MEBIUS_TOKEN}, with a token from Settings › Tokens
MCPHosted at https://www.mebius.design/api/mcp, with browser sign-in
Code stackReact 19, TypeScript and Tailwind CSS v4, in shadcn registry format
Price$19 per kit, paid once, or $259 for all items. No subscription.
Counts as of19 Nov 2026, live from the catalog

Install a mebius.design kit’s theme on its own first, then its items with --overwrite. For Relivo, the point-of-sale dashboard kit:

Terminal
npx shadcn@latest add @mebius/relivo-theme
npx shadcn@latest add @mebius/relivo-metrics-dashboard --overwrite

The quickest test of the @mebius registry needs no purchase: sign up free and install any of the free charts or forms with the same commands.

How do AI agents install from a shadcn registry?

Over MCP, checked in shadcn’s docs on 19 Nov 2026.

The shadcn CLI includes an MCP server, so an AI editor can browse, search and install items by prompt from every registry in components.json: shadcn/ui’s own, third-party, private and namespaced ones (shadcn’s MCP docs). One command sets it up for Claude Code, and the same init takes cursor, vscode, codex or opencode:

Terminal
npx shadcn@latest mcp init --client claude

mebius.design also runs a hosted MCP server at https://www.mebius.design/api/mcp. It signs in through the browser and has five read-only tools that return each item’s source, usage docs and install commands, theme first. Setup for Claude Code, Cursor and VS Code is in the shadcn MCP and CLI guide.

FAQ

Answers to what people ask most.

Is a shadcn registry the same as an npm package?

No. An npm package installs into node_modules and changes when you bump its version. A shadcn registry item is copied into your own files by the shadcn CLI, so you edit it freely and re-run the add command to take a newer version.

Do you need components.json to install from a shadcn registry?

The project needs one, which npx shadcn@latest init creates. A registries entry in it is needed only for a registry that isn’t in shadcn’s directory or that needs a token. URL and GitHub installs need no entry.

Is the @mebius registry in the shadcn directory?

Yes. shadcn merged @mebius into its registry directory on 19 Nov 2026 (pull request #12763). The 20 open starter items install with npx shadcn@latest add @mebius/<item> and no setup. The other items need a mebius.design token.

Can you sell components through a shadcn registry?

Yes, with a private registry that serves items only to valid tokens. mebius.design sells 19 UI kits this way, at $19 per kit, paid once, or $259 for all items. See Pricing.

What does a free mebius.design account unlock in the @mebius registry?

All 62 charts and 128 forms, with their Figma files, through the shadcn CLI and the mebius MCP server. A kit you buy adds its components and blocks, and every purchase covers client work for one person (License).

How do you add your own registry to the shadcn directory?

Make the registry open source, public, flat and valid against the schema, with no file content in its index. Then add an entry to apps/v4/registry/directory.json in shadcn-ui/ui, run pnpm validate:registries and open a pull request.

Item pages, kits and guides this guide uses.