# Getting Started

Learn how to get setup and run your own component registry.

Source: https://webjs.dev/ui/docs/registry/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, helpers or other files you would like to distribute.

A registry is a set of JSON files served over HTTP. The CLI reads it from a base URL you pass with `--registry`, so any host that serves static files can run one, a WebJs app included.

## Requirements

You are free to design and publish your custom registry as you see fit. The only requirement is that your registry items conform to the [registry-item schema specification](https://webjs.dev/ui/docs/registry/registry-item-json), and that the registry serves two kinds of files under one base URL:

- `<url>/<name>.json` for every item, with each file's `content` inlined. `add` and `view` fetch these.
- `<url>/index.json`, a JSON array of the items. `list` and `diff` fetch this.

Your registry can be a WebJs app or any other server, static host or CDN, as long as it serves those files as JSON over HTTP. The `build` command below writes both from one [registry.json](https://webjs.dev/ui/docs/registry/registry-json) file.

## registry.json

The `registry.json` is the source of the registry. It contains the registry's name, homepage, and defines all the items present in the registry. `webjsui build` reads it and writes the files the CLI fetches.

Here's an example `registry.json` file:

```json title="registry.json"
{
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "brand-button",
      "type": "registry:ui",
      "title": "Brand Button",
      "description": "A button in the Acme brand colors.",
      "files": [
        {
          "path": "components/brand-button.ts",
          "type": "registry:ui"
        }
      ]
    }
  ]
}
```

## Structure your registry

Define all items in a single root `registry.json`. Add every item to its `items` array. File paths are relative to the `registry.json` file.

A registry is one `registry.json`. `build` reads its `items`, so a larger registry keeps one manifest and organizes its source files in folders.

```json title="registry.json"
{
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "brand-button",
      "type": "registry:ui",
      "title": "Brand Button",
      "description": "A button in the Acme brand colors.",
      "files": [
        {
          "path": "components/brand-button.ts",
          "type": "registry:ui"
        }
      ]
    },
    {
      "name": "hello-world",
      "type": "registry:block",
      "title": "Hello World",
      "description": "A simple hello world page.",
      "registryDependencies": ["brand-button"],
      "files": [
        {
          "path": "blocks/hello-world/page.ts",
          "type": "registry:page",
          "target": "app/hello/page.ts"
        }
      ]
    }
  ]
}
```

This `registry.json` file must conform to the [registry schema specification](https://webjs.dev/ui/docs/registry/registry-json).

## Add an item

### Create a UI component

Add your first item. Here's an example of a simple brand button, written the way the kit writes a Tier-1 component: a function that returns the classes for a native `<button>`.

```ts title="components/brand-button.ts"
import { cn } from '../lib/utils.ts';

export function brandButtonClass(opts: { className?: string } = {}): string {
  return cn(
    'rounded-md bg-neutral-900 px-4 py-2 text-sm font-medium text-white',
    opts.className,
  );
}
```

**Note:** This example places the component in the `components` directory and imports `cn()` as `../lib/utils.ts`, the layout the kit's own registry uses. On install, the CLI rewrites that import to the `cn()` file in the user's project, wherever their `components.json` puts it. See Guidelines.

```txt
components
└── brand-button.ts
lib
└── utils.ts
```

### Add the item to the registry

To add your component to the registry, add an item definition to `registry.json`.

```json title="registry.json"
{
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "brand-button",
      "type": "registry:ui",
      "title": "Brand Button",
      "description": "A button in the Acme brand colors.",
      "files": [
        {
          "path": "components/brand-button.ts",
          "type": "registry:ui"
        }
      ]
    }
  ]
}
```

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. The `path` is relative to the `registry.json` file. The `type` decides the folder the file is written to in the user's project, unless the file names a `target`.

You can read more about the registry item schema and file types in the [registry item schema docs](https://webjs.dev/ui/docs/registry/registry-item-json).

## Serve your registry

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

### Option A: Static JSON files

Run the build command to generate static registry JSON files.

```bash
npx @webjsdev/ui build
```

`build` reads `registry.json`, inlines the content of every file it lists, and writes one `<name>.json` per item, the `index.json` the CLI lists from, and a copy of the manifest as `registry.json`.

**Note:** By default, the build command writes the registry JSON files to `./r`, e.g. `r/brand-button.json`. You can change the output directory by passing the `--output` option. See the [build command](https://webjs.dev/ui/docs/cli#build) for more information.

A WebJs app serves everything under `public/` at `/`, so build into it:

```bash
npx @webjsdev/ui build --output public/r
```

Then run the app.

```bash
npm run dev
```

Your files will now be served at `http://localhost:8080/public/r/[NAME].json` e.g. `http://localhost:8080/public/r/brand-button.json`, and the registry's base URL is `http://localhost:8080/public/r`.

### Option B: Route handlers

If you want to serve registry JSON from a route, a WebJs `route.ts` handler can answer `/r/<name>.json`. The route below serves the files `build` wrote. It is the same shape as the route webjs.dev itself serves the WebJs UI registry from.

```ts title="app/r/[name]/route.ts"
import { readFile } from 'node:fs/promises';
import { join } from 'node:path';

const OUT = join(process.cwd(), 'registry-out');

export async function GET(_req: Request, { params }: { params: { name: string } }) {
  // The CLI asks for <name>.json, and the segment arrives with the suffix.
  const name = params.name.replace(/\.json$/, '');
  if (!/^[a-z0-9-]+$/.test(name)) {
    return Response.json({ error: 'Not found.' }, { status: 404 });
  }
  try {
    const body = await readFile(join(OUT, `${name}.json`), 'utf8');
    return new Response(body, { headers: { 'content-type': 'application/json' } });
  } catch {
    return Response.json({ error: `Registry item "${name}" was not found.` }, { status: 404 });
  }
}
```

Build into that folder with `build --output registry-out`. The same route answers `/r/index.json`, since `index` is just another file in the output.

**Content negotiation**

The CLI requests `<url>/<name>.json` with a plain `fetch`, like any other client. Serve the registry under its own path, such as `/r`, rather than at the root of a site.

## Test your registry

After your registry is being served, test it with the same CLI commands that other developers will use. Every command that reads a registry takes its base URL with `--registry`.

### Using URL

`list` reads `<url>/index.json`. `view` and `add` read `<url>/<name>.json` for the item you name.

#### List items

Start by confirming that the registry index can be read.

```bash
npx @webjsdev/ui list --registry http://localhost:8080/public/r
```

`list` shows the items typed `registry:ui` and `registry:block`, in Components, Blocks and Charts groups. Items of other types install with `add` but are not listed.

#### Search items

`search` is another name for `list`. Its argument filters by a substring of the item name.

```bash
npx @webjsdev/ui search button --registry http://localhost:8080/public/r
```

#### View an item

Then view one registry item by name.

```bash
npx @webjsdev/ui view brand-button --registry http://localhost:8080/public/r
```

#### Add an item

To test the install flow, run `add` from a project where you want to install the item. The project needs a `components.json`, which `webjs ui init` writes.

```bash
npx @webjsdev/ui add brand-button --registry http://localhost:8080/public/r
```

### Using an environment variable

When you run several commands against one registry, set the `REGISTRY_URL` environment variable instead of passing `--registry` each time. It changes the default for every command.

```bash
export REGISTRY_URL=http://localhost:8080/public/r

npx @webjsdev/ui list
npx @webjsdev/ui add brand-button
```

See the [Namespaces](https://webjs.dev/ui/docs/registry/namespace) page for what the CLI supports in place of namespaced registries.

## Publish your registry

To make your registry available to other developers, publish your project to a public URL. Once deployed, users install items by passing your base URL to `add`.

### Share install instructions

Tell users the command, with your base URL in it. The base URL is the folder that holds the item files, not a template, and the CLI appends `/<name>.json` to it.

```bash
npx @webjsdev/ui add brand-button --registry https://acme.com/r
```

Each command names its registry with `--registry` or `REGISTRY_URL`.

### Add your registry to the directory

If your registry is open source and publicly available, you can add it to the [registry directory](https://webjs.dev/ui/docs/directory), which shows readers the command that installs from it.

See the [Registry Directory](https://webjs.dev/ui/docs/registry/registry-index) docs for the submission requirements.

## Guidelines

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

- Lay your files out the way the kit's registry does: components in `components/<name>.ts`, the `cn()` helper imported as `../lib/utils.ts`. On install the CLI rewrites a relative import that lands on `lib/utils.ts`, `lib/dom.ts`, `lib/icons.ts`, a `components/<name>.ts` file, or another file of the same item, to wherever that file lands in the user's project. Any other import is left as written.
- For blocks, the following properties are required: `name`, `description`, `type` and `files`. Give every block file a `target`, so a page lands at its route (`app/hello/page.ts`) instead of at its registry path.
- It is recommended to add a proper name and description to your registry item. This helps LLMs understand the component and its purpose, and `list` prints the description.
- Make sure to list all registry dependencies in `registryDependencies`. A registry dependency is the name of another item in the same registry, eg. `brand-button`. It is fetched from the same base URL as the item that lists it.
- Make sure to list all dependencies in `dependencies`. A dependency is the name of an npm package eg. `zod`. To set a version, you can use the `name@version` format eg. `zod@^3.20.0`. `add` installs them with the package manager the project uses.
- Write the component for a WebJs app: a Tier-1 helper returns classes for a native element, and a Tier-2 element extends `WebComponent` from `@webjsdev/core`. See the [introduction](https://webjs.dev/ui/docs) for the two tiers.
