You can turn any public GitHub repository into a registry.
Add a registry.json file to the root of the repo, describe the files you want to share, and users can install them with the shadcn-svelte CLI.
You do not need to set up a registry server or publish generated JSON files. The GitHub repository becomes the source registry.
Distribute Anything
Registry items are not limited to components or Svelte code. They can include any files from your repository: source files, configuration, docs, templates, workflows, rules, or project conventions.
When to use GitHub
Use a GitHub registry when:
- You already have reusable code in a public GitHub repository.
- You want users to install directly from
owner/repo/item. - You want to distribute config files, rules, docs, templates, utilities, or any other files from the same repository.
- You do not need private repo access or custom request authentication.
Requirements
A GitHub registry must:
- Be a public
github.comrepository. - Have a
registry.jsonfile at the repository root. - Use valid
registry.jsonandregistry-item.jsonschemas. - Reference source files that exist in the repository.
Private repositories and GitHub Enterprise hosts are not currently supported by GitHub addresses.
Step 1: Add registry.json
Given an existing public repository:
.
├── .editorconfig
├── AGENTS.md
└── docs
└── conventions.mdAdd registry.json at the root of the repository.
.
├── registry.json
├── .editorconfig
├── AGENTS.md
└── docs
└── conventions.mdDefine the item you want to distribute.
{
"$schema": "https://shadcn-svelte.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"
}
]
}
]
}Commit and push the file.
git add registry.json
git commit -m "add registry"
git pushUsers can now install the item from GitHub.
Step 2: Distribute any file
A registry item can install one file or many files. Use the files array to declare the files that belong together.
Use target when a file should be written to a specific destination in the user's project.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"items": [
{
"name": "vitest-setup",
"type": "registry:item",
"title": "Vitest Setup",
"description": "A Vitest setup with project defaults and docs.",
"files": [
{
"path": "config/vitest.config.ts",
"type": "registry:file",
"target": "~/vitest.config.ts"
},
{
"path": "test/setup.ts",
"type": "registry:file",
"target": "~/test/setup.ts"
},
{
"path": "docs/testing.md",
"type": "registry:file",
"target": "~/docs/testing.md"
}
]
}
]
}Step 3: Validate the registry
Before sharing the registry, validate it from the CLI.
The command reads the root registry.json, resolves includes, validates the registry items, and checks that referenced files exist.
You can also validate a branch, tag, or commit SHA.
Organize with include
For larger repositories, keep item definitions close to the source files they describe.
registry.json
config
├── prettier.config.mjs
└── registry.json
rules
├── agent.md
└── registry.jsonThe root registry.json can include the nested registry files.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"include": ["config/registry.json", "rules/registry.json"]
}The included registry file declares items for that directory.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"items": [
{
"name": "agent-rules",
"type": "registry:file",
"files": [
{
"path": "agent.md",
"type": "registry:file",
"target": "~/AGENTS.md"
}
]
}
]
}When using include, file paths are relative to the registry.json file that declares the item.
Registry dependencies
Use registryDependencies when one registry item depends on another registry item.
For dependencies in the same GitHub repository, use the full GitHub item address.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"items": [
{
"name": "project-setup",
"type": "registry:item",
"registryDependencies": [
"acme/toolkit/agent-rules",
"acme/toolkit/prettier-config",
"acme/toolkit/tsconfig"
],
"files": [
{
"path": "docs/project-setup.md",
"type": "registry:file",
"target": "~/docs/project-setup.md"
}
]
}
]
}Items can also depend on external registries. Use the full item address for the registry that owns the dependency.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"items": [
{
"name": "workspace-setup",
"type": "registry:item",
"registryDependencies": ["button", "contoso/devtools/prettier-config"],
"files": [
{
"path": "docs/workspace.md",
"type": "registry:file",
"target": "~/docs/workspace.md"
}
]
}
]
}Refs are not inherited across dependencies. If a dependency should be pinned, include its own ref.
{
"$schema": "https://shadcn-svelte.com/schema/registry.json",
"name": "acme-toolkit",
"homepage": "https://github.com/acme/toolkit",
"items": [
{
"name": "project-setup",
"type": "registry:item",
"registryDependencies": [
"acme/toolkit/agent-rules#v1.0.0",
"acme/toolkit/tsconfig#c0ffee254729296a45d6691db565cf707a3fef5d"
],
"files": [
{
"path": "docs/project-setup.md",
"type": "registry:file",
"target": "~/docs/project-setup.md"
}
]
}
]
}Useful commands
Validate a GitHub registry.
Install an item from a GitHub registry.
Install an item whose registry item name contains /.
For GitHub item addresses, the first two path segments are the GitHub owner and repository. Any remaining segments are the registry item name, not a file path. An address ending in .json is treated as a file path.
Install from a tag.
Install from a full commit SHA.
Refs
Use #ref to install from a branch, tag, or commit SHA.
Refs may contain slashes.
If no ref is provided, the CLI uses the repository default branch.
The CLI uses Git to resolve branches, tags, and short refs into a commit SHA before reading files. Full 40-character commit SHAs are used directly and do not require Git.
Review before installing
GitHub registry items install code and project files from public repositories. Treat a GitHub item address like any other third-party code dependency.
Before installing from a source you do not control:
- Review the repository and the root
registry.json. - Review the item definition, especially
files,target,dependencies,devDependencies, andregistryDependencies. - Check any external registry dependencies. They can install files from other registries.
- Prefer pinned refs for published install commands. A full 40-character commit SHA is the most reproducible option.