shadcn GitHub Registries: Ship Components from Any Public Repo

shadcn just killed the need for a registry server. Starting this month, any public GitHub repository can act as a fully functional shadcn registry — no hosting infrastructure, no build pipeline, no published JSON. Drop a registry.json at your repo root, and the shadcn CLI handles the rest.

This sounds like a small quality-of-life win. It is not. It’s a quiet reframe of what shadcn actually is.

What GitHub Registries Are

Until now, distributing custom shadcn components required either running a server, publishing generated item files, or accepting that each project would drift away from the shared source. Teams chose one of three bad options: an npm package that broke shadcn’s “own your code” philosophy, a self-hosted registry server with deployment overhead, or manual copy-pasting that introduced drift immediately.

GitHub Registries eliminate that tradeoff. Add a registry.json to any public GitHub repository, and the shadcn CLI can install from it directly using a simple address format:

npx shadcn@latest add owner/repo/item-name
npx shadcn@latest add acme/ui/button#v2.1.0

The first two path segments are the GitHub owner and repository. Everything after is the item name. Append a #ref to pin to a branch, tag, or commit SHA — the CLI resolves branches and tags to commit SHAs automatically. Full 40-character SHAs skip Git resolution entirely.

It’s Not Just Components

Here’s the part most coverage misses: GitHub Registries are not limited to UI components. The official registry docs list what a registry item can distribute — and the list is longer than expected:

• Components, hooks, and utilities (the obvious ones)
• Design tokens and Tailwind theme variables
• Agent instructions — AGENTS.md files for Claude Code, Cursor, and Copilot
• Testing setup, CI workflows, and release pipelines
• Project conventions, editor configs, and documentation stubs
• Codemods and migration kits

That last category matters more than it sounds. shadcn launched its Skills system earlier this year — distributable AI agent context packs that give coding agents accurate knowledge about your component APIs and patterns. With GitHub Registries, a team can ship AGENTS.md alongside their design system components. One command syncs both.

Setting Up a GitHub Registry

Create a registry.json at the root of your public GitHub repository:

{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "files": [
        {
          "path": "components/ui/button.tsx",
          "type": "registry:ui"
        }
      ]
    }
  ]
}

Push to GitHub. Your repository is now a registry. Users install your component with:

npx shadcn@latest add your-org/your-repo/button

To distribute project conventions — AGENTS.md, editor configs, CI templates — add a second item using the target field to install files outside the components/ directory:

{
  "name": "project-conventions",
  "description": "Shared project conventions and agent instructions",
  "files": [
    {
      "path": "docs/AGENTS.md",
      "target": "~/AGENTS.md"
    },
    {
      "path": "configs/.editorconfig",
      "target": "~/.editorconfig"
    }
  ]
}

The Constraint Worth Knowing

GitHub Registries require a public repository. Private repositories and GitHub Enterprise hosts are not currently supported. Teams that need private distribution should use namespaced registries with authentication — a separate workflow that preserves the hosted registry model for internal use.

This is not a blocker for open-source design systems or shared public toolkits. For confidential internal component libraries, it is a limitation for now.

One Security Note

Installing from a GitHub registry carries the same trust model as npm install. Registry items can install code, configuration files, and templates anywhere in your project. Before running shadcn add from a source you do not control, review the registry.json and the item definition — specifically the files, dependencies, and envVars fields. The official docs call this out directly. Treat unknown registries like unknown npm packages: read before you run.

What This Changes

shadcn has been shipping at a high clip. CLI v4 in March 2026, the Rhea compact style in May 2026, GitHub Registries in June 2026. The direction is clear: shadcn is becoming a distribution platform for developer artifacts, not just a component collection.

The GitHub Registry model fits how most teams already work. Code lives in GitHub. Conventions live in GitHub. Agent instructions increasingly live in GitHub. Making that repository directly addressable by the shadcn CLI removes the last reason to treat component distribution as a separate infrastructure problem.

For teams sharing UI across multiple projects, this is the architecture update worth acting on. Add a registry.json to your next public repo. Future you will appreciate it.