registry-item.json
Specification for registry items.
The registry-item.json schema is used to define your custom registry items. It is what the CLI fetches from <url>/<name>.json, with each file's content inlined.
{
"name": "hello-world",
"type": "registry:block",
"title": "Hello World",
"description": "A simple hello world page.",
"registryDependencies": ["brand-button"],
"dependencies": ["[email protected]", "zod"],
"devDependencies": ["@types/node"],
"files": [
{
"path": "blocks/hello-world/page.ts",
"type": "registry:page",
"target": "app/hello/page.ts"
},
{
"path": "blocks/hello-world/components/hello-world.ts",
"type": "registry:component"
}
],
"cssVars": {
"theme": {
"font-heading": "Poppins, sans-serif"
},
"light": {
"brand": "oklch(0.205 0.015 18)"
},
"dark": {
"brand": "oklch(0.205 0.015 18)"
}
}
}
Definitions
The schema is registryItemSchema, exported from @webjsdev/ui/registry/schema. See the API Reference.
$schema
The $schema property is accepted and not checked. webjsui build stamps every item it writes with one.
name
The name of the item. This is used to identify the item in the registry: the CLI fetches it as <url>/<name>.json. It should be unique for your registry.
{
"name": "hello-world"
}
title
A human-readable title for your registry item. Keep it short and descriptive.
{
"title": "Hello World"
}
description
A description of your registry item. This can be longer and more detailed than the title. list prints it beside the name.
{
"description": "A simple hello world page."
}
type
The type property is used to specify the type of your registry item.
{
"type": "registry:block"
}
The following types are accepted. The item's type decides how list groups it and how add treats an existing file. Where each file lands is decided by the file's own type, see files.
list shows only registry:ui and registry:block items. Every type installs with add.
author
The author property is used to specify the author of the registry item. It is accepted and kept in the item, and the CLI does not print it.
{
"author": "John Doe <[email protected]>"
}
dependencies
The dependencies property is used to specify the dependencies of your registry item. This is for npm packages. add installs them with the package manager the project uses, and adds @webjsdev/core to the list.
Use @version to specify the version of a package.
{
"dependencies": ["zod", "date-fns", "[email protected]"]
}
devDependencies
The devDependencies property is used to specify the dev dependencies of your registry item. These are npm packages that are only needed during development. add installs them with the dev flag.
Use @version to specify the version of the package.
{
"devDependencies": ["@types/node", "[email protected]"]
}
registryDependencies
Used for registry dependencies. Each entry is the name of another item in the same registry, fetched from the same base URL as the item that lists it.
{
"registryDependencies": ["brand-button", "brand-card"]
}
The CLI resolves them transitively and installs the deepest dependency first. A name it has already visited is skipped, so a cycle cannot loop.
Note: Every dependency comes from the item's own registry. A bare name such as button means button.json in your registry, not the WebJs UI button.
files
The files property is used to specify the files of your registry item. Each file has a path, type, content and an optional target.
The target property is required for registry:page and registry:file types.
{
"files": [
{
"path": "blocks/hello-world/page.ts",
"type": "registry:page",
"target": "app/hello/page.ts"
},
{
"path": "blocks/hello-world/components/hello-world.ts",
"type": "registry:component"
},
{
"path": "blocks/hello-world/lib/format-greeting.ts",
"type": "registry:lib"
},
{
"path": "blocks/hello-world/.env.example",
"type": "registry:file",
"target": ".env.example"
}
]
}
path
The path property is used to specify the path to the file in your registry. build reads the file from it, relative to registry.json. On install, the CLI resolves the file's relative imports against it, see Imports.
content
The file's source, as a string. The CLI writes a file only from content and never fetches a file by its path, so a served item must carry it. build inlines it.
type
The type property is used to specify the type of the file. Without a target, it decides where the file lands, from the folders in the project's components.json.
target
The target property is used to indicate where the file should be placed in a project. It is a path from the project root, written as is, and it wins over the file type. Use it for routes, config, and every file of a block.
A target is a path from the project root, written as is. A target such as @ui/button.ts is written to a folder named @ui. To land a file in the user's configured folder, leave out target and pick the file type.
Imports
On install, a relative import is resolved against the file's path in the registry and rewritten to where its target lands in the project, when it points at another file of the same item, lib/utils.ts (the user's cn() file), lib/dom.ts, lib/icons.ts, or a components/<name>.ts file (the aliases.ui folder). Any other import is left as written.
tailwind
DEPRECATED: Use cssVars.theme instead for Tailwind v4 projects.
cssVars
Use to define CSS variables for your registry item. add writes them to the stylesheet components.json names: theme in the @theme inline block, light in :root, dark in .dark. A block that is missing is appended.
{
"cssVars": {
"theme": {
"font-heading": "Poppins, sans-serif",
"color-brand": "var(--brand)"
},
"light": {
"brand": "oklch(0.205 0.015 18)",
"radius": "0.5rem"
},
"dark": {
"brand": "oklch(0.985 0 0)"
}
}
}
Only variables the stylesheet does not define yet are added. An existing one keeps its value, so cssVars adds tokens and never overrides them.
css
To ship rules such as @layer base, @utility or @keyframes, add a CSS file as a registry:file with a target, and tell users to import it into their stylesheet.
envVars
To ship example variables, add an .env.example file as a registry:file, as above.
font
Ship a font as files and cssVars.theme entries, such as "font-heading": "Poppins, sans-serif".
docs
The docs property is accepted by the schema, and the CLI does not print it on install. Put install notes in the description, which list and view show.
categories
Use categories to organize your registry item. list --category filters blocks by them, and the chart category marks a block as a chart.
{
"categories": ["sidebar", "dashboard"]
}
meta
Use meta to add additional metadata to your registry item. You can add any key/value pair, for your own tools to read.
{
"meta": { "foo": "bar" }
}