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:
The package exposes three entry points:
@webjsdev/ui/registry/schemafor the registry, item andcomponents.jsonschemas.@webjsdev/ui/registry/extractfor the projector that turns the packaged registry into the view the CLI and the MCP server print.@webjsdev/ui/utilsfor reading and writingcomponents.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);
@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'ornull.primaryCategory(item)returns the category a block is grouped under.installCommand(name)returnsnpx @webjsdev/ui add <name>.renderComponentText(projection)andrenderBlockText(projection)render a projection as the textviewprints.extractHelperSignatures(src),extractHelperAxes(src)andextractDocHeader(src)read a Tier-1 source's helper signatures, variant options and JSDoc header.BLOCK_DEFINITIONandCHART_CATEGORYare 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?)parsescomponents.jsonwithrawConfigSchemaand addsresolvedPaths, the absolute paths the aliases point at. It returnsnullwhen the file is missing and throws when it does not conform.writeConfig(cwd, config)writescomponents.json.CONFIG_FILEis'components.json'.loggeris 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.