---
title: "What Is a shadcn Registry? How to Install From One"
description: "A shadcn registry serves components as JSON that the shadcn CLI installs by name, URL or @namespace. How items, namespaces, tokens, the directory and MCP work."
url: https://www.mebius.design/guides/what-is-a-shadcn-registry
updated: 2026-11-19
---

# 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](https://ui.shadcn.com/docs/registry) 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](https://www.mebius.design/guides/figma-to-react-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](https://ui.shadcn.com/docs/registry/registry-item-json). The fields that matter when you install:

- `name` and `type`: the item’s ID and kind. The schema has 12 types: base, block, component, font, hook, lib, page, file, style, theme, ui and item, each written as registry:\<type>.
- `dependencies`: npm packages the CLI installs, with an optional @version.
- `registryDependencies`: other items the item needs, written as a bare name for shadcn/ui’s own (button), as @namespace/name, as a GitHub path or as a full URL. The CLI resolves each one from its own registry.
- `files`: each file’s path and type, with an optional target folder.
- `cssVars` and `css`: theme, light and dark variables, and CSS rules the CLI adds to your stylesheet.
- `docs` and `envVars`: a message printed after install, and environment variables the item expects.

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

```bash title="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.

```bash title="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](https://ui.shadcn.com/docs/registry/github) 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](https://ui.shadcn.com/docs/registry/namespace) allow two forms:

- A string: the URL template alone, for a public registry. The `{name}` placeholder is required and becomes the item name. An optional `{style}` becomes your project’s style.
- An object: `url` plus `headers` or `params`, for registries that need a token. Values can read environment variables written as `${VAR_NAME}`.

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

```json title="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](https://ui.shadcn.com/docs/registry/authentication) 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](https://www.mebius.design/settings/tokens) (a free account works), then use the object form and put the token in .env.local:

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

```bash title=".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:

- 401: the token is missing, unknown or revoked.
- 403: the item belongs to a kit the account doesn’t own.
- 404: no item has that name. Item names start with their kit, like @mebius/relivo-button.

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](https://www.mebius.design/guides/install-shadcn-components-cli-mcp).

## 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](https://ui.shadcn.com/docs/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](https://ui.shadcn.com/docs/registry/registry-index) ask for a registry that is:

- Open source and publicly accessible.
- Valid against the registry schema.
- Flat: registry.json and each item’s file at the root, with no nested items.
- Free of file content in its index. Content belongs in each item’s own file.

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](https://github.com/shadcn-ui/ui/pull/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 directory**: Listed since 19 Nov 2026 ([pull request #12763](https://github.com/shadcn-ui/ui/pull/12763))
- **Open starter**: 20 charts and forms, MIT, no account or token ([source on GitHub](https://github.com/mebius-designs/mebius-starter))
- **Free with an account**: 62 [charts](https://www.mebius.design/freebies/charts) and 128 [forms](https://www.mebius.design/freebies/forms), each with its Figma file
- **Paid kits**: 19 kits with React code: 2,046 components and 1,061 blocks
- **Auth**: `Authorization: Bearer ${MEBIUS_TOKEN}`, with a token from [Settings › Tokens](https://www.mebius.design/settings/tokens)
- **MCP**: Hosted at `https://www.mebius.design/api/mcp`, with browser sign-in
- **Code stack**: React 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 of**: 19 Nov 2026, live from the catalog

Install a mebius.design kit’s theme on its own first, then its items with `--overwrite`. For [Relivo](https://www.mebius.design/resources/relivo), the point-of-sale dashboard kit:

```bash title="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](https://www.mebius.design/signup) 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](https://ui.shadcn.com/docs/mcp)). One command sets it up for Claude Code, and the same init takes cursor, vscode, codex or opencode:

```bash title="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](https://www.mebius.design/guides/install-shadcn-components-cli-mcp).

## 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](https://www.mebius.design/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](https://www.mebius.design/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.

## Related

Item pages, kits and guides this guide uses.

- [shadcn MCP & CLI](https://www.mebius.design/guides/install-shadcn-components-cli-mcp): Every command for the @mebius registry, plus the shadcn and mebius MCP servers.
- [Figma to React](https://www.mebius.design/guides/figma-to-react-shadcn-registry): The author’s side: how a registry is built from a Figma design system.
- [Tailwind Plus vs shadcn/ui](https://www.mebius.design/guides/tailwind-plus-vs-shadcn): Price, license, Figma files and theming of the two, and where mebius.design fits.
- [Free charts](https://www.mebius.design/freebies/charts): 62 animated chart cards to install from the @mebius registry.
