# API Reference

Programmatic API for registry schemas, the kit projector and components.json.

Source: https://webjs.dev/ui/docs/registry/api-reference

The `@webjsdev/ui` package exports a small programmatic API for tools that read registries, validate items, or show the kit to an agent.

A WebJs app does not depend on `@webjsdev/ui` (it arrives with the WebJs CLI, and copied components import only `@webjsdev/core`), so add it as a dev dependency to use the API from a script:

```bash
npm install -D @webjsdev/ui
```

The package exposes three entry points:

- `@webjsdev/ui/registry/schema` for the registry, item and `components.json` schemas.
- `@webjsdev/ui/registry/extract` for the projector that turns the packaged registry into the view the CLI and the MCP server print.
- `@webjsdev/ui/utils` for reading and writing `components.json`.

The bare `@webjsdev/ui` entry is the CLI itself and runs it when imported, so import a subpath. Fetching, resolving and installing items happen inside the CLI commands.

## @webjsdev/ui/registry/schema

The schemas are [zod](https://zod.dev) schemas of the registry format. Use them to validate registry files or a project's config.

```ts
import { registrySchema, registryItemSchema } from '@webjsdev/ui/registry/schema';

const manifest = registrySchema.parse(JSON.parse(text));
const result = registryItemSchema.safeParse(item);
if (!result.success) console.error(result.error.issues);
```

| Export | Validates |
| --- | --- |
| `registrySchema` | A `registry.json`: `name`, `homepage`, `items`. |
| `registryItemSchema` | One registry item, as served at `<url>/<name>.json`. |
| `registryIndexSchema` | The `index.json` array. |
| `registryItemTypeSchema` | An item or file `type`, e.g. `registry:ui`. |
| `registryItemFileSchema` | One entry of `files`. `target` is required for `registry:file` and `registry:page`. |
| `registryItemCssVarsSchema` | `cssVars`: `theme`, `light`, `dark`. |
| `registryItemCommonSchema` | The item fields shared by every type. |
| `registryItemTailwindSchema`, `registryItemCssSchema`, `registryItemEnvVarsSchema` | The `tailwind`, `css` and `envVars` fields. |
| `rawConfigSchema` | A project's `components.json`. |
| `lintConfigSchema`, `lintRuleSchema`, `lintSeveritySchema` | The `lint` block of `components.json`. |

## @webjsdev/ui/registry/extract

The projector reads the registry that ships inside the package, with no network, and returns the agent-facing view of it. `webjsui view`, `webjsui list` and the MCP `ui` tool all call it, so a tool built on it prints what they print. Every source it returns is baked for a style, so it holds plain Tailwind classes.

### uiInventory

Returns one entry per component, sorted by name.

```ts
uiInventory(): Array<{ name: string, tier: 1 | 2, helpers: string[], dependencies: string[] }>
```

### uiComponent

Returns one component's projection, or `null` when the name is not a `registry:ui` item. `style` picks the style to bake with, `new-york` when omitted.

```ts
uiComponent(name: string, opts?: { style?: string }): {
  name: string, tier: 1 | 2, type: string,
  description: string, helpers: string[], example: string,
  dependencies: string[], registryDependencies: string[],
} | null
```

### uiComponentFiles

Returns a component's files, baked, as `add` writes them, or `null` for an unknown name.

```ts
uiComponentFiles(name: string, opts?: { style?: string }): Array<{ path: string, content: string }> | null
```

### uiBlocks

Lists blocks and charts, and components when `type` asks for them. Pass an index as the second argument to list another registry's, for example one fetched from `<url>/index.json`.

```ts
uiBlocks(
  opts?: { type?: 'ui' | 'block' | 'chart' | 'all', category?: string },
  index?: RegistryItem[],
): Array<{ name: string, type: 'ui' | 'block' | 'chart', categories: string[], description: string }>
```

```ts
import { uiBlocks } from '@webjsdev/ui/registry/extract';

const index = await (await fetch('https://acme.com/r/index.json')).json();
const logins = uiBlocks({ type: 'block', category: 'login' }, index);
```

### uiBlock

Returns one block's projection by name, from the packaged registry: its description, categories, dependencies, the install command and its files with their targets. `source: true` includes the file contents.

```ts
uiBlock(name: string, opts?: { style?: string, source?: boolean }): BlockProjection | null
```

### projectBlock

The same projection as `uiBlock`, over an item you already have, such as one fetched from a custom registry. Returns `null` when the item is not a block.

```ts
projectBlock(item: RegistryItem, opts?: { style?: string, source?: boolean }): BlockProjection | null
```

### uiBlockIndex

Returns the block and chart names grouped by category, with no descriptions. This is the compact listing the MCP `ui` tool returns with no arguments.

```ts
uiBlockIndex(index?: RegistryItem[]): { blocks: Record<string, string[]>, charts: Record<string, string[]> }
```

### Other exports

- `itemKind(item)` returns `'ui'`, `'block'`, `'chart'` or `null`.
- `primaryCategory(item)` returns the category a block is grouped under.
- `installCommand(name)` returns `npx @webjsdev/ui add <name>`.
- `renderComponentText(projection)` and `renderBlockText(projection)` render a projection as the text `view` prints.
- `extractHelperSignatures(src)`, `extractHelperAxes(src)` and `extractDocHeader(src)` read a Tier-1 source's helper signatures, variant options and JSDoc header.
- `BLOCK_DEFINITION` and `CHART_CATEGORY` are the constants the listings use.

## @webjsdev/ui/utils

Reads and writes a project's `components.json`.

```ts
import { getConfig, writeConfig, CONFIG_FILE } from '@webjsdev/ui/utils';

const config = getConfig(process.cwd());
if (config) console.log(config.aliases.ui, config.resolvedPaths.ui);
```

- `getConfig(cwd?)` parses `components.json` with `rawConfigSchema` and adds `resolvedPaths`, the absolute paths the aliases point at. It returns `null` when the file is missing and throws when it does not conform.
- `writeConfig(cwd, config)` writes `components.json`.
- `CONFIG_FILE` is `'components.json'`.
- `logger` is the CLI's console logger.

## Errors

The schemas throw a `ZodError` from `parse`, or return `{ success: false, error }` from `safeParse`. The projector functions return `null` for a name they do not know rather than throwing.
