8.0k New

GitHub Registries

Previous Next

Use a public GitHub repository as a registry.

Epicenter

Local-first, open source apps

Special Sponsor

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.

pnpm dlx shadcn-svelte@latest add <username>/<repo>/<item>

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.

Use case Example files
Components src/lib/date-picker.svelte src/lib/data-table.svelte
Helpers and utilities src/lib/format-date.ts src/lib/utils.ts src/lib/hooks/use-copy.svelte.ts
Design system packages tokens/colors.json styles/theme.css src/lib/components/*
Feature kits src/routes/(auth)/* src/lib/auth.ts src/lib/login-form.svelte
Agent workflows AGENTS.md .cursor/rules/* .claude/commands/*
Project conventions .editorconfig biome.json docs/conventions.md
Codemods and migration kits codemods/* scripts/migrate.ts docs/migration.md
Testing setup vitest.config.ts test/setup.ts docs/testing.md
CI and release workflows .github/workflows/ci.yml .github/workflows/release.yml
Project automation scripts/release.ts scripts/checks.ts docs/automation.md
Issue and pull request templates .github/ISSUE_TEMPLATE/* .github/pull_request_template.md
MCP configuration .mcp.json .cursor/mcp.json

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.com repository.
  • Have a registry.json file at the repository root.
  • Use valid registry.json and registry-item.json schemas.
  • 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.md

Add registry.json at the root of the repository.

.
├── registry.json
├── .editorconfig
├── AGENTS.md
└── docs
    └── conventions.md

Define the item you want to distribute.

registry.json
{
  "$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 push

Users can now install the item from GitHub.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions

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.

registry.json
{
  "$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"
        }
      ]
    }
  ]
}
pnpm dlx shadcn-svelte@latest add acme/toolkit/vitest-setup

Step 3: Validate the registry

Before sharing the registry, validate it from the CLI.

pnpm dlx shadcn-svelte@latest registry validate acme/toolkit

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.

pnpm dlx shadcn-svelte@latest registry validate acme/toolkit#v1.0.0

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.json

The root registry.json can include the nested registry files.

registry.json
{
  "$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.

rules/registry.json
{
  "$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.

pnpm dlx shadcn-svelte@latest add acme/toolkit/agent-rules

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.

registry.json
{
  "$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.

registry.json
{
  "$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.

registry.json
{
  "$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.

pnpm dlx shadcn-svelte@latest registry validate acme/toolkit

Install an item from a GitHub registry.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions

Install an item whose registry item name contains /.

pnpm dlx shadcn-svelte@latest add acme/toolkit/rules/agent

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.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions#v1.0.0

Install from a full commit SHA.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions#c0ffee254729296a45d6691db565cf707a3fef5d

Refs

Use #ref to install from a branch, tag, or commit SHA.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions#main

Refs may contain slashes.

pnpm dlx shadcn-svelte@latest add acme/toolkit/project-conventions#feature/conventions

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, and registryDependencies.
  • 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.