# GitHub Registries · JGuang UI

> Use a public GitHub repository as a registry.

- Page: https://jiguang132.com/systems/jguang-ui/docs/registry/github
- Based on: shadcn/ui documentation (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c

You can now 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 `JGuang UI Registry` CLI.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

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 React code.** They can include
any files from your repository: source files, configuration, docs, templates,
workflows, rules or project conventions.


  

    
Use case

    
Example files

  

  {[
    ["Components", "components/date-picker.tsx", "components/data-table.tsx"],
    [
      "Helpers and utilities",
      "lib/format-date.ts",
      "lib/cn.ts",
      "hooks/use-copy.ts",
    ],
    [
      "Design system packages",
      "tokens/colors.json",
      "styles/theme.css",
      "components/*",
    ],
    [
      "Feature kits",
      "app/(auth)/*",
      "lib/auth.ts",
      "components/login-form.tsx",
    ],
    ["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"],
  ].map(([label, ...files]) => (
    

      
{label}

      

        {files.map((file) => (
          
{file}

        ))}
      

    

  ))}


## 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. For private or authenticated registries, use a
[namespace](/systems/jguang-ui/docs/registry/namespace) with
[authentication](/systems/jguang-ui/docs/registry/authentication).

## Step 1: Add registry.json

Given an existing public repository:

```txt
.
├── ...
├── .editorconfig
├── AGENTS.md
└── docs
    └── conventions.md
```

Add `registry.json` at the root of the repository.

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

Define the item you want to distribute.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Commit and push the file.

```bash
git add registry.json
```

```bash
git commit -m "add registry"
```

```bash
git push
```

Users can now install the item from GitHub.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

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

For example, a testing setup can install a Vitest config, a setup file and a
short team guide.

```txt
registry.json
config
└── vitest.config.ts
docs
└── testing.md
test
└── setup.ts
```

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Users install it the same way.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Use `target` when a file should be written to a specific destination in the
user's project.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Step 3: Validate the registry

Before sharing the registry, validate it from the CLI.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

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.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Step 4: List and search items

Use `list` to see every item in the repository registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Use `search` to filter the catalog.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Use `view` to inspect one item payload.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Organize with include

For larger repositories, keep item definitions close to the source files they
describe.

```txt
registry.json
config
├── prettier.config.mjs
└── registry.json
rules
├── agent.md
└── registry.json
```

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

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

The included registry file declares items for that directory.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

When using `include`, file paths are relative to the `registry.json` file that
declares the item.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Registry dependencies

Use `registryDependencies` when one registry item depends on another registry
item.

### Same repository dependencies

For dependencies in the same GitHub repository, use the full GitHub item
address.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

A docs item can depend on a template item from the same repository.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

A CI setup can depend on the same formatting and testing defaults that users can
install separately.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### External registry dependencies

Items can also depend on external registries. Use the full item address for the
registry that owns the dependency.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

### Dependency refs

Refs are not inherited across dependencies. If a dependency should be pinned,
include its own ref.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Useful commands

List every item in a GitHub registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Search a GitHub registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Validate a GitHub registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Install an item from a GitHub registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

View an item from a GitHub registry.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Install an item whose registry item name contains `/`.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```


  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.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Install from a full commit SHA.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

## Refs

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

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

Refs may contain slashes.

```text
Use the JGuang UI Registry URL provided on /systems/jguang-ui#install.
```

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`, `registryDependencies` and `envVars`.
- 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.
- Use `JGuang UI Registry` to inspect the resolved
  item payload before installing.
- Pipe `JGuang UI Registry` output to your agent or review tool if you want help
  checking the item.
- Use `JGuang UI Registry` to preview an
  install without writing files.
- Use `--diff` or `--view` with `JGuang UI Registry` to inspect file changes or file
  contents before applying them.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt