Skip to content
WebJs
Menu

Getting Started

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

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, 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 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:

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.

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.

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

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.

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.

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.

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.

pnpm dlx @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 for more information.

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

pnpm dlx @webjsdev/ui build --output public/r

Then run the app.

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.

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.

pnpm dlx @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.

pnpm dlx @webjsdev/ui search button --registry http://localhost:8080/public/r

View an item

Then view one registry item by name.

pnpm dlx @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.

pnpm dlx @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.

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

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

See the Namespaces 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.

pnpm dlx @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, which shows readers the command that installs from it.

See the Registry Directory 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 for the two tiers.