Epicenter
Local-first, open source apps
You can turn any 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 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 a custom registry server or request authentication.
Requirements
A GitHub registry must:
- Be a
github.comrepository. - Have a
registry.jsonfile at the repository root. - Use valid
registry.jsonandregistry-item.jsonschemas. - Reference source files that exist in the repository.
Public repositories work with zero configuration. Private repositories work with GitHub credentials. See Private repositories.
GitHub Enterprise hosts are not supported by GitHub addresses. Use a custom registry URL when a registry server needs request authentication.
Step 1: Add registry.json
Given an existing 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.
Private repositories
Private github.com repositories work as registries too. You do not set up a server or configure anything in the registry itself. If you can read the repository, the CLI can install from it.
Use the GitHub CLI
For local development, authenticate with the GitHub CLI once:
gh auth loginThen install from the private repository like any other GitHub registry.
When a repository is not publicly readable, the CLI reads it through gh using your stored credentials. The token stays inside the GitHub CLI. It never enters the shadcn-svelte process.
The first time a command uses your credentials, it prints a notice:
✔ Using gh credentials.Use a token in CI
Where the GitHub CLI is not installed, set GH_TOKEN or GITHUB_TOKEN:
GH_TOKEN=github_pat_xxx npx shadcn-svelte@latest add acme/private-toolkit/project-conventionsGH_TOKENtakes precedence overGITHUB_TOKEN.- Use a fine-grained personal access token scoped to the repository, with Contents: Read-only access. This is the recommended credential.
- When a token is set, it is used instead of the GitHub CLI and is only ever sent to
api.github.com.
In GitHub Actions, the built-in
GITHUB_TOKENcan generally only read the repository that owns the workflow. To install from a private registry in another repository, use a fine-grained personal access token or a GitHub App installation token.
How it works
- Public repositories are always read anonymously. No credentials are used and the GitHub CLI is never invoked.
- The CLI tries anonymous access first. It only uses your credentials when the repository's root
registry.jsonis not publicly readable. - Ref resolution runs
git ls-remotefirst. Git may already use a credential helper you have configured, for example one installed bygh auth setup-git. - Private files are read through GitHub's Contents API, pinned to the resolved commit SHA.
- GitHub returns the same not-found response for private and missing repositories. If your credentials cannot read the repository either, the CLI cannot tell you which case it was.
Limits
- Registry source files are limited to 5 MiB per file.
- GitHub Enterprise hosts are not supported. GitHub addresses always resolve against
github.com. - Avoid symlinks in registry source files. Anonymous reads return the symlink target path as text, while authenticated reads through the Contents API return the target file's content.
Review before installing
GitHub registry items install code and project files from GitHub 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.