# Namespaces

Use more than one registry, one registry per command.

Source: https://webjs.dev/ui/docs/registry/namespace

One registry per command.

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`.

```bash
npx @webjsdev/ui add auth-utils --registry https://acme.com/r
```

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.

```bash
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.

```txt
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.

```bash
npx @webjsdev/ui view auth-utils --registry https://acme.com/r
```

### 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.

```bash
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](https://webjs.dev/ui/docs/registry/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.

```bash
npx @webjsdev/ui view auth-utils --registry https://acme.com/r
```

## 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.

```json title="dashboard.json"
{
  "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.

```bash
npx @webjsdev/ui add auth-utils --registry https://acme.com/r/v2
```

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

```bash
# 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

```txt
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

```txt
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](https://webjs.dev/ui/docs/registry/authentication) describes.

## Creating Your Own Registry

To make a registry, build it with `webjsui build` and serve the output folder. See [Getting Started](https://webjs.dev/ui/docs/registry/getting-started).

## Troubleshooting

- **Items install from the wrong registry.** Check for a `REGISTRY_URL` left set in the shell. It applies to every command without a `--registry` flag.
- **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.** `list` shows only `registry:ui` and `registry:block` items.
