Skip to content
WebJs
Menu

API Reference

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

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:

pnpm add -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 schemas of the registry format. Use them to validate registry files or a project's config.

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);
ExportValidates
registrySchemaA registry.json: name, homepage, items.
registryItemSchemaOne registry item, as served at <url>/<name>.json.
registryIndexSchemaThe index.json array.
registryItemTypeSchemaAn item or file type, e.g. registry:ui.
registryItemFileSchemaOne entry of files. target is required for registry:file and registry:page.
registryItemCssVarsSchemacssVars: theme, light, dark.
registryItemCommonSchemaThe item fields shared by every type.
registryItemTailwindSchema, registryItemCssSchema, registryItemEnvVarsSchemaThe tailwind, css and envVars fields.
rawConfigSchemaA project's components.json.
lintConfigSchema, lintRuleSchema, lintSeveritySchemaThe 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.

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.

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.

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.

uiBlocks(
  opts?: { type?: 'ui' | 'block' | 'chart' | 'all', category?: string },
  index?: RegistryItem[],
): Array<{ name: string, type: 'ui' | 'block' | 'chart', categories: string[], description: string }>
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.

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.

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.

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.

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.