Each command reads one registry: the one --registry names, else the one the REGISTRY_URL environment variable names, else the WebJs UI registry. This page covers how to work with several registries.
Overview
A registry is addressed by its base URL, and the item by its name inside it. The CLI fetches <url>/<name>.json.
Every item named in one command, and every registry dependency they pull in, comes from that one registry. To install from two registries, run two commands.
npx @webjsdev/ui add button card
npx @webjsdev/ui add auth-utils --registry https://acme.com/r
Multiple registries
Nothing stops a team from running several registries, split by resource type, by team or by stability. Each one is a base URL, and each install command names the one it reads from.
https://registry.acme.com/ui # components
https://registry.acme.com/blocks # pages and views
https://registry.acme.com/beta # experimental items
Configuration
Per command
Pass the base URL with --registry. init, add, list, view and diff all take it.
Per session
Set REGISTRY_URL to change the default for every command, for example in a shell or a CI job that installs only from your registry.
export REGISTRY_URL=https://acme.com/r
npx @webjsdev/ui list
npx @webjsdev/ui add auth-utils
components.json
Name the registry with --registry or REGISTRY_URL. The registries field in components.json is accepted only so an older file still parses.
Authentication & Security
The CLI fetches each file with a plain request. See Authentication for how to protect a private registry.
Inspecting Resources Before Installation
Run view to print an item and the source of every file it would write before you install it.
Dependency Resolution
An item's registryDependencies are names, and each is fetched from the same base URL as the item that lists it. The CLI walks them depth first and installs the deepest dependency first, so an item lands after everything it imports. A name it has already visited is skipped, which also guards against cycles.
{
"name": "dashboard",
"type": "registry:block",
"registryDependencies": ["card", "chart"]
}
Here card and chart are fetched from the registry dashboard came from, not from the WebJs UI registry. A registry that builds on kit components either ships its own copies as items or asks users to install the kit components first.
Overriding Third-Party Resources
Every file the CLI writes becomes your source. To customize a third-party component, install it and edit the file. diff then shows how your copy differs from the registry's.
Versioning
The base URL is any prefix the CLI appends /<name>.json to, so put the version in the path.
Keep a query string out of the base URL. The CLI appends the item path after it, so https://acme.com/r?v=2 requests https://acme.com/r?v=2/auth-utils.json.
CLI Commands
# Install from a specific registry
npx @webjsdev/ui add auth-utils --registry https://acme.com/r
# Install several items from one registry
npx @webjsdev/ui add auth-utils login-form --registry https://acme.com/r
# View an item
npx @webjsdev/ui view auth-utils --registry https://acme.com/r
# List a registry (search is the same command)
npx @webjsdev/ui list --registry https://acme.com/r
npx @webjsdev/ui search auth --registry https://acme.com/r
# Compare installed files against a registry
npx @webjsdev/ui diff --registry https://acme.com/r
Error Handling
Resource Not Found
Failed to fetch registry item "auth-utils" from https://acme.com/r/auth-utils.json: HTTP 404
Check the item name and the base URL. The URL in the message is the exact one the CLI requested.
Index Not Found
Failed to fetch registry index from https://acme.com/r/index.json: HTTP 404
list and diff need <url>/index.json. webjsui build writes it.
Authentication Failures
A registry that answers 401 or 403 fails the same way, with that status in the message. Make the registry reachable without credentials, as Authentication describes.
Creating Your Own Registry
To make a registry, build it with webjsui build and serve the output folder. See Getting Started.
Troubleshooting
- Items install from the wrong registry. Check for a
REGISTRY_URLleft set in the shell. It applies to every command without a--registryflag. - A dependency is not found. Registry dependencies resolve in the same registry as the item. Make sure each name exists there.
- An item installs but does not list.
listshows onlyregistry:uiandregistry:blockitems.