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>.jsonfor every item, with each file'scontentinlined.addandviewfetch these.<url>/index.json, a JSON array of the items.listanddifffetch 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:
{
"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.
{
"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>.
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.
{
"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.
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:
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.
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.
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.
View an item
Then view one registry item by name.
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.
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.
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, thecn()helper imported as../lib/utils.ts. On install the CLI rewrites a relative import that lands onlib/utils.ts,lib/dom.ts,lib/icons.ts, acomponents/<name>.tsfile, 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,typeandfiles. Give every block file atarget, 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
listprints 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 thename@versionformat eg.zod@^3.20.0.addinstalls 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
WebComponentfrom@webjsdev/core. See the introduction for the two tiers.