Skip to content
WebJs
Menu

Dynamic Search

How the CLI searches a registry, and what a large registry can do.

search is another name for list. It fetches your registry's index.json and filters the items locally. This works for any registry and requires nothing more than a static file.

Search runs in the CLI.

The CLI filters the index it fetched, so every registry gets search from a static index.json, with nothing to implement on the server.

How It Works

When you run search, the CLI requests the index once and filters what comes back:

pnpm dlx @webjsdev/ui search button --registry https://acme.com/r
GET https://acme.com/r/index.json

The index must be a JSON array of registry items. The CLI keeps the items typed registry:ui and registry:block, applies the filters below, and prints them in groups, Components then Blocks.

Filters

Every filter runs in the CLI, against the index it fetched.

FilterDescription
[filter]Keeps the items whose name contains this substring.
--type <type>ui, block, chart or all (the default). A chart is a registry:block item with the chart category.
--category <name>Keeps the blocks and charts whose categories include this name.
--jsonPrints one compact JSON array of { name, type, categories, description }, for a script or an agent.
pnpm dlx @webjsdev/ui list --type block --category login --json --registry https://acme.com/r

Response Format

Serve the whole index as a JSON array. webjsui build writes one with each item's name, type and description, which keeps it small however large the registry grows, since no file contents are in it.

index.json
[
  { "name": "brand-button", "type": "registry:ui", "description": "A button in the Acme brand colors." },
  { "name": "login-01", "type": "registry:block", "description": "A simple login form." }
]

The --category filter reads each entry's categories, which the index build writes leaves out. A registry that wants category filtering serves an index whose entries carry categories, from its own route or script.

Large Registries

For a registry with thousands of items, keep the index lean: names, types, descriptions and categories, never contents. The CLI downloads it once per command. Each item's full JSON is fetched only when someone views or installs that item.

Testing

Test your index with curl:

curl https://acme.com/r/index.json

Then verify with the CLI:

pnpm dlx @webjsdev/ui search button --registry https://acme.com/r