Getting Started

This guide will walk you through the process of setting up your own registry. It assumes you already have a project with components, hooks, utilities or other files you would like to distribute.

If you have an existing public GitHub repository, you can turn it into a registry by adding a registry.json file at the root. See GitHub Registries for details.

If you're starting a new registry project, you can use the registry template as a starting point. We have already configured it for you.

Requirements

You are free to design and publish your custom registry as you see fit. The only requirement is that your registry catalog and registry items must conform to the registry schema specification and registry-item schema specification.

Your registry can be a Next.js, Vite, Vue, Svelte, PHP or any other framework as long as it supports serving JSON over HTTP. It can also be a public GitHub repository with a registry.json file at the root.

If you'd like to see an example of a registry, we have a template project for you to use as a starting point.

registry.json

The registry.json is the entry point for the registry. It contains the registry's name, homepage, and defines all the items present in the registry.

Your registry must have this file (or JSON payload) present at the root of the registry endpoint. The registry endpoint is the URL where your registry is hosted.

Here's an example registry.json file:

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

Structure your registry

You can structure your source registry in one of two ways:

• Define all items in a single root registry.json.
• Use a root registry.json with include to compose multiple registry.json files.

Option A: Single registry.json

Create a registry.json file in the root of your project. Add all your registry items to the items array. This is the simplest way to define a registry.

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

This registry.json file must conform to the registry schema specification.

Option B: Using include

For larger registries, you can use include to compose your source registry from multiple registry.json files.

registry.json
components
└── ui
    ├── button.tsx
    ├── input.tsx
    └── registry.json
hooks
├── registry.json
├── use-media-query.ts
└── use-toggle.ts

The root registry.json defines the registry metadata and includes the nested registry files.

{/* prettier-ignore */}

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

Included registry.json files are valid registry files for composition and may omit name and homepage. Only the root registry.json must define the registry metadata.

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

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.

Add an item

Create a UI component

Add your first item. Here's an example of a simple `` component:

import * as React from "react"

export function Button(props: React.ComponentProps<"button">) {
  return (
    <button
      {...props}
      className="rounded-md bg-neutral-900 px-4 py-2 text-sm font-medium text-white"
    />
  )
}

Note: This example places the component in the components/ui directory. You can place it anywhere in your project as long as you set the correct path in the registry.json file.

components
└── ui
    └── button.tsx

Add the item to the registry

To add your component to the registry, add an item definition to registry.json. If you are using include, add the item to the included registry.json file that owns the component. For example, add a UI component to components/ui/registry.json.

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

You define your registry item by adding a name, type, title, description and files.

For every file you add, you must specify the path and type of the file. In a single-file registry, the path is relative to the root of your project. When using include, the path is relative to the registry.json file that declares the item. The type is the type of the file.

You can read more about the registry item schema and file types in the registry item schema docs.

Serve your registry

You can serve your registry as static JSON files or from dynamic route handlers.

Option A: Static JSON files

Run the build command to generate static registry JSON files.

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

If your source registry uses include, JGuang UI Registry resolves the included registries and writes a flattened registry to your output directory. The generated registry.json does not contain include.

Note: By default, the build command will generate the registry JSON files in public/r e.g public/r/button.json. You can change the output directory by passing the --output option. See the JGuang UI build command for more information.

If you're running your registry on Next.js, you can serve these files by running the next server. The command might differ for other frameworks.

npm run dev

Your files will now be served at http://localhost:3000/r/[NAME].json eg. http://localhost:3000/r/button.json.

Option B: Dynamic route handlers

If you want to serve registry JSON from your source registry.json at request time, use the producer-side loader APIs from JGuang UI Registry.

Install JGuang UI Registry as a runtime dependency:

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

Use loadRegistry to serve the registry catalog.

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

Use loadRegistryItem to serve individual registry items.

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

Both loaders resolve include before returning JSON, so route handlers can use the same source registry.json structure without running JGuang UI Registry.

Content negotiation

The JGuang UI Registry CLI supports HTTP Content Negotiation. This allows you to host your registry at any endpoint — including the root of your domain — and serve different content depending on who is asking.

From a single URL, you can serve:

HTML to browsers — a landing page, documentation, or marketing site.

JSON to the JGuang UI CLI — an installable registry item.

Markdown to AI agents and LLMs — a machine-readable version of your content.

The client signals its preference using the Accept request header, and your server decides what to return.

Request headers

When the CLI makes a request to a registry, it sends the following headers:

• User-Agent: JGuang UI Registry
• Accept: JGuang UI Registry

Root hosting

By checking these headers on your server, you can route CLI traffic to an installable registry item while keeping browser traffic flowing to your documentation or homepage.

The examples below assume your built registry item is served at /r/index.json. Adjust the path to match your output.

In Next.js, express this as a rewrite in next.config.ts. This keeps the negotiation in the routing layer and avoids a Proxy function for this static rewrite:

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

Or, in an Express.js server:

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

This enables:

Branded Registry URLs :{" "}

JGuang UI add https://ui.example.com

Shorter URLs : Users type your domain root, not{" "}

/r/ or /registry/ sub-paths.

Easy Mnemonics : Easier for users to remember and share your registry.

Test your registry

After your registry is being served, test it with the same CLI commands that other developers will use.

Using URL

Use the catalog URL for commands that discover items, like list and search. Use item URLs for commands that read or install a specific item, like view and add.

List items

Start by confirming that the registry catalog can be discovered.

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

Search items

Search the registry by query.

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

View an item

Then view one registry item by name.

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

Add an item

To test the install flow, run add from a project where you want to install the item.

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

Using namespace

Add the registry

You can also test your registry with a namespace. From a project with a components.json file, add your registry URL template to the project.

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

The {name} placeholder must resolve to an item JSON file. For example, @acme/button resolves to http://localhost:3000/r/button.json. The catalog is still served separately at http://localhost:3000/r/registry.json.

List items

Then list the items in your registry.

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

Search items

Search the registry by query.

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

View an item

View one registry item by name.

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

Add an item

To test the install flow, run add from a project where you want to install the item.

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

See the Namespaced Registries docs for more information.

Publish your registry

To make your registry available to other developers, publish your project to a public URL. Once deployed, users can install items directly from item URLs, or they can add your registry as a namespace in their project.

Share namespace setup instructions

If you want users to install items with a namespace like @acme/button, tell them to add your registry URL template to their project. The {name} placeholder is replaced by the item name when the CLI resolves the registry item.

The template must resolve to item JSON files. For example, @acme/button resolves to https://acme.com/r/button.json. Your registry catalog should still be served separately at https://acme.com/r/registry.json.

They can add the namespace with the CLI.

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

Or they can add it manually under the registries field in their components.json file.

{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}

Users can then consume items from your registry by namespace.

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

Add your namespace to the registry index

If your registry is open source and publicly available, you can submit your namespace to the official registry index. This lets users add your namespace by name instead of pasting the full URL template.

See the Registry Index docs for the submission requirements.

Guidelines

Here are some guidelines to follow when building components for a registry.

• Place your registry item in the registry/[STYLE]/[NAME] directory. I'm using default as an example. It can be anything you want as long as it's nested under the registry directory.
• For blocks, the following properties are required: name, description, type and files.
• It is recommended to add a proper name and description to your registry item. This helps LLMs understand the component and its purpose.
• Make sure to list all registry dependencies in registryDependencies. A registry dependency is an item address such as button, @acme/input-form, acme/ui/button or http://localhost:3000/r/editor.json.
• Make sure to list all dependencies in dependencies. A dependency is the name of the package in the registry eg. zod, sonner, etc. To set a version, you can use the name@version format eg. zod@^3.20.0.
• Imports should always use the @/registry path. eg. import { HelloWorld } from "@/registry/default/hello-world/hello-world"
• Ideally, place your files within a registry item in components, hooks, lib directories.