# registry-item.json

Specification for registry items.

Source: https://webjs.dev/ui/docs/registry/registry-item-json

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.

```json title="registry-item.json"
{
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "A simple hello world page.",
  "registryDependencies": ["brand-button"],
  "dependencies": ["is-even@3.0.0", "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)"
    }
  }
}
```

[See more examples](https://webjs.dev/ui/docs/registry/examples)

## Definitions

The schema is `registryItemSchema`, exported from `@webjsdev/ui/registry/schema`. See the [API Reference](https://webjs.dev/ui/docs/registry/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.

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

### title

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

```json title="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.

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

### type

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

```json title="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.

| Type | Description |
| --- | --- |
| `registry:ui` | Use 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:block` | Use 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:component` | Use for simple components. |
| `registry:lib` | Use for lib and utils. |
| `registry:hook` | Use for reusable logic, such as a reactive controller. |
| `registry:page` | Use for page or file-based routes. |
| `registry:file` | Use for miscellaneous files. |
| `registry:theme` | Use for themes. |
| `registry:style` | Use for registry styles. |
| `registry:item` | Use for universal registry items. |
| `registry:base`, `registry:font`, `registry:example`, `registry:internal` | Accepted, 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.

```json title="registry-item.json"
{
  "author": "John Doe <john@doe.com>"
}
```

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

```json title="registry-item.json"
{
  "dependencies": ["zod", "date-fns", "name@1.0.2"]
}
```

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

```json title="registry-item.json"
{
  "devDependencies": ["@types/node", "name@1.2.0"]
}
```

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

```json title="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.**

```json title="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 type | Written to |
| --- | --- |
| `registry:ui` | The `aliases.ui` folder, `components/ui` by default. |
| `registry:component` | The `aliases.components` folder, `components` by default. |
| `registry:lib` | The `aliases.lib` folder, `lib` by default. |
| `registry:hook` | `hooks`. |
| `registry:block` | Its own `path`, from the project root. |
| Any other type | The 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.

```json title="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.

```json title="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.

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