# Getting Started · JGuang UI

> 本页提供 JGuang UI 技术内容、中文导航与术语适配。

- 页面: https://jiguang132.com/zh/systems/jguang-ui/docs/registry/getting-started
- 改编自: shadcn/ui 文档 (MIT) @ bc0705384b51252af26dcc65425b216bf5eb063c
- 说明：正文保留英文原文。

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](/systems/jguang-ui/docs/registry/github) for details.

If you're starting a new registry project, you can use the [registry template](/systems/jguang-ui#open-source-attribution) 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](/systems/jguang-ui/docs/registry/registry-json) and [registry-item schema specification](/systems/jguang-ui/docs/registry/registry-item-json).

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](/systems/jguang-ui#open-source-attribution) 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:

```text
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.

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

This `registry.json` file must conform to the [registry schema specification](/systems/jguang-ui/docs/registry/registry-json).

### Option B: Using include

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

```txt
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 */}
```text
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.

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

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:

```tsx title="components/ui/button.tsx" showLineNumbers
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.


```txt
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`.

```text
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](/systems/jguang-ui/docs/registry/registry-item-json).

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

```text
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](/systems/jguang-ui/docs/cli#build) 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.

```bash
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:

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

Use `loadRegistry` to serve the registry catalog.

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

Use `loadRegistryItem` to serve individual registry items.

```text
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:

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

Or, in an Express.js server:

```text
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.

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

#### Search items

Search the registry by query.

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

#### View an item

Then view one registry item by name.

```text
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.

```text
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.

```text
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.

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

#### Search items

Search the registry by query.

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

#### View an item

View one registry item by name.

```text
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.

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

See the [Namespaced Registries](/systems/jguang-ui/docs/registry/namespace) 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.

```text
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.

```json title="components.json" showLineNumbers
{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}
```

Users can then consume items from your registry by namespace.

```text
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](/systems/jguang-ui/docs/registry/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.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt