GitHub Registry: Turn Any Repo Into a shadcn Registry

A GitHub registry turns any GitHub repository into a source that anyone can install code from with a single command. You don't need a registry server, a build step or published JSON. You add one registry.json file to your repo.

Maybe you want to reuse a component, a config file or a set of team conventions across projects. The usual options are to publish an npm package, copy and paste between repos, or host your own registry. A GitHub registry is simpler than any of them. This guide covers what a GitHub registry is, how to create one, what you can share with it, and when it is the right choice.

Looking for GitHub Packages? This guide is about shadcn GitHub registries, which distribute source files from a repository. GitHub's package and container registry (npm.pkg.github.com, ghcr.io) is a different product for publishing packages and Docker images.

What is a GitHub registry?

A GitHub registry is a GitHub repository with a registry.json file at its root. The file lists installable items, and the shadcn CLI reads it directly from GitHub. Each item describes which files to add to a project, where to put them and what they depend on.

The shadcn CLI is best known for commands like npx shadcn@latest add button. Behind that command is a registry: a catalog of installable items. Unlike a package manager, shadcn copies the source code into your project, so you own the code and can change it freely.

Before GitHub registries, publishing your own registry meant running a server or building and hosting generated JSON files. That is a lot of work if all you want is to share a few files with your team or the community. With a GitHub registry, the repository itself is the registry.

GitHub registry vs. hosted registry

Users install from a GitHub registry with an address made of the GitHub owner, the repository and the item name:

npx shadcn@latest add owner/repo/item

Here is how a GitHub registry compares to a traditional hosted registry:

How to create a GitHub registry

Creating a GitHub registry takes four steps:

1. Add a registry.json file to the root of your repository.
2. Define your items, listing the files each item installs and where they go.
3. Check the file with the shadcn CLI's validate command.
4. Push to GitHub. Your GitHub registry is live, and anyone can install from it.

Say your repository acme/toolkit contains an AGENTS.md, an .editorconfig and a conventions doc. This registry.json turns it into a GitHub registry with one item:

{  "$schema": "https://ui.shadcn.com/schema/registry.json",  "name": "acme-toolkit",  "homepage": "https://github.com/acme/toolkit",  "items": [    {      "name": "project-conventions",      "type": "registry:item",      "title": "Project Conventions",      "description": "Shared project conventions, editor settings and agent instructions.",      "files": [        { "path": "AGENTS.md", "type": "registry:file", "target": "~/AGENTS.md" },        { "path": ".editorconfig", "type": "registry:file", "target": "~/.editorconfig" },        { "path": "docs/conventions.md", "type": "registry:file", "target": "~/docs/conventions.md" }      ]    }  ]}

After you push, anyone can install the whole bundle into their project:

npx shadcn@latest add acme/toolkit/project-conventions

The CLI can also list, search and view the items in any GitHub registry. Items can depend on other items, and large repos can split their registry definitions across several files. For every option, see the official shadcn GitHub registry docs.

What you can share with a GitHub registry

The biggest change is not about hosting. It is about what a registry item can contain. Items in a GitHub registry can include any files from your repository, not just React components.

UI and application code

• Components such as date pickers and data tables
• Hooks and utilities like use-copy.ts or format-date.ts
• Design system packages with tokens, themes and components
• Full feature kits, for example an auth flow with routes, helpers and a login form

Project setup

• Editor and linter configs such as .editorconfig or biome.json
• Testing setups with a Vitest config and setup files
• CI and release workflows in .github/workflows/
• Issue and pull request templates

AI agent workflows

• AGENTS.md files with project instructions
• Cursor rules in .cursor/rules/
• Claude commands in .claude/commands/
• MCP configuration files such as .mcp.json

Team conventions and migrations

• Convention docs and project standards
• Codemods and migration scripts

So a GitHub registry is more than a component registry. It also lets you share how your team works: the configs, rules and tooling that every new project should start with.

Versioning a GitHub registry

Versioning uses Git refs. Add # followed by a branch, tag or commit SHA to any install address:

npx shadcn@latest add acme/toolkit/project-conventions#v1.0.0

Without a ref, the CLI uses the repository's default branch. In install commands you publish for others, a full commit SHA is the most reproducible option.

Using a private GitHub registry

A private repository works as a GitHub registry with no extra setup in registry.json. If you are signed in with the GitHub CLI (gh auth login), shadcn can read any repo you have access to. In CI, set a GH_TOKEN or GITHUB_TOKEN with read-only access to the repository contents.

This makes a private GitHub registry an easy way to share internal components, configs and agent rules across a company without publishing anything publicly.

A note on safety: installing from a GitHub registry adds third-party code and files to your project, so treat it like any other dependency. Use npx shadcn@latest view to inspect an item, or add --dry-run to preview an install before any files are written.

Who should use a GitHub registry?

A GitHub registry is a great fit if you are:

• A component or design system author who wants users to install straight from your repo.
• A team standardizing setup across many repositories, from lint rules to CI workflows.
• Sharing AI agent rules such as AGENTS.md, Cursor rules or MCP configs.
• An open source maintainer looking for a short, memorable install command.

It is not the right fit if you need GitHub Enterprise (addresses always resolve against github.com) or a custom registry server with request authentication. For those cases, shadcn supports namespaced registries with authentication.

GitHub registry vs. npm package vs. copy-paste

npm packages are still the right choice for libraries you want to update centrally. A GitHub registry works best for code and files that people should own and customize after installing.

FAQ

What is a GitHub registry?

A GitHub registry is a GitHub repository with a registry.json file at its root. The file describes installable items, and users add them to their projects with npx shadcn@latest add owner/repo/item.

How do I create a GitHub registry?

Add a registry.json file to the root of your repository, list the items and files you want to share, and push to GitHub. No server or build step is needed.

Is a shadcn GitHub registry the same as GitHub Packages?

No. GitHub Packages and the GitHub Container Registry publish npm packages and Docker images. A shadcn GitHub registry copies source files from a repository directly into your project.

Can I use a private repo as a GitHub registry?

Yes. The shadcn CLI uses your GitHub CLI login or a GH_TOKEN / GITHUB_TOKEN environment variable to read private repositories you have access to.

What files can a GitHub registry item include?

Any files from your repository: components, hooks, utilities, configs, docs, templates, CI workflows, AI agent rules, MCP configs and more.

How do I version items in a GitHub registry?

Add a Git ref to the install address, for example #main, #v1.0.0 or a full commit SHA. Without a ref, the default branch is used.

Does a GitHub registry work with GitHub Enterprise?

No. GitHub registry addresses always resolve against github.com. For other setups, use a namespaced registry.

Conclusion

A GitHub registry removes the biggest hurdle to sharing code with shadcn: you no longer need to run a registry. One registry.json file turns any repository into a distribution channel for components, configs, conventions and AI agent workflows.

Create a GitHub registry from a repository you already have, then browse GitHub registries on shadhub to see what others are sharing.