Skip to content
WebJs
Menu

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.

registry-item.json
{
  "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.

registry-item.json
{
  "name": "hello-world"
}

title

A human-readable title for your registry item. Keep it short and descriptive.

registry-item.json
{
  "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.

registry-item.json
{
  "description": "A simple hello world page."
}

type

The type property is used to specify the type of your registry item.

registry-item.json
{
  "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.

TypeDescription
registry:uiUse for UI components and single-file primitives. Listed under Components. A Tier-1 file's @example block is replaced with a pointer to view on install.
registry:blockUse for ready-made views with multiple files. Listed under Blocks, or Charts with the chart category. An existing file is kept unless --overwrite is passed.
registry:componentUse for simple components.
registry:libUse for lib and utils.
registry:hookUse for reusable logic, such as a reactive controller.
registry:pageUse for page or file-based routes.
registry:fileUse for miscellaneous files.
registry:themeUse for themes.
registry:styleUse for registry styles.
registry:itemUse for universal registry items.
registry:base, registry:font, registry:example, registry:internalAccepted, so registries that use them still validate. The CLI gives them no special handling.

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.

registry-item.json
{
  "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.

registry-item.json
{
  "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.

registry-item.json
{
  "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.

registry-item.json
{
  "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.

registry-item.json
{
  "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.

File typeWritten to
registry:uiThe aliases.ui folder, components/ui by default.
registry:componentThe aliases.components folder, components by default.
registry:libThe aliases.lib folder, lib by default.
registry:hookhooks.
registry:blockIts own path, from the project root.
Any other typeThe project root, by file name.

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.

registry-item.json
{
  "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.

registry-item.json
{
  "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.

registry-item.json
{
  "meta": { "foo": "bar" }
}