JGuang / JGuang UI
RegistryRegistry

GitHub Registries

Use a public GitHub repository as a registry.

Partially translated: Chinese navigation, titles, descriptions, and common headings. The technical body is currently in English.

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.

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 with authentication.

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.

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

Commit and push the file.

git add registry.json

git commit -m "add registry"

git push

Users can now install the item from GitHub.

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.

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

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

Users install it the same way.

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.

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

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.

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.

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.

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

Use search to filter the catalog.

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

Use view to inspect one item payload.

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.

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

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

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

The included registry file declares items for that directory.

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.

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.

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.

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.

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.

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.

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

Useful commands

List every item in a GitHub registry.

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

Search a GitHub registry.

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

Validate a GitHub registry.

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

Install an item from a GitHub registry.

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

View an item from a GitHub registry.

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

Install an item whose registry item name contains /.

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.

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

Install from a full commit SHA.

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

Refs

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

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

Refs may contain slashes.

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.

Source: registry/github.mdx

Technical documentation for JGuang UI.

Getting StartedGetting Started

Learn how to get setup and run your own component registry.本页提供 JGuang UI 技术内容、中文导航与术语适配。

MCP ServerMCP Server

MCP support for registry developers本页提供 JGuang UI 技术内容、中文导航与术语适配。

On this page

Distribute AnythingWhen to use GitHubRequirementsStep 1: Add registry.jsonStep 2: Distribute any fileStep 3: Validate the registryStep 4: List and search itemsOrganize with includeRegistry dependenciesSame repository dependenciesExternal registry dependenciesDependency refsUseful commandsRefsReview before installing