# FAQ

Frequently asked questions about running a registry.

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

## Frequently asked questions

### What does a complex component look like?

Here's an example of a complex component that installs a page, two components, a helper and a config file.

```json
{
  "name": "hello-world",
  "title": "Hello World",
  "type": "registry:block",
  "description": "A complex hello world component",
  "files": [
    {
      "path": "blocks/hello-world/page.ts",
      "type": "registry:page",
      "target": "app/hello/page.ts"
    },
    {
      "path": "blocks/hello-world/components/hello-world.ts",
      "type": "registry:component"
    },
    {
      "path": "blocks/hello-world/components/formatted-message.ts",
      "type": "registry:component"
    },
    {
      "path": "blocks/hello-world/lib/format-date.ts",
      "type": "registry:lib"
    },
    {
      "path": "blocks/hello-world/hello.config.ts",
      "type": "registry:file",
      "target": "hello.config.ts"
    }
  ]
}
```

The page lands at its `target`, the two components in the project's `components` folder, the helper in its `lib` folder, and the config file at the project root. A `target` is a path from the project root, written as is.

### How do I add a new Tailwind color?

To add a new color you need to add it to `cssVars` under `light` and `dark` keys, and map it to a Tailwind color under `theme`.

```json
{
  "name": "hello-world",
  "title": "Hello World",
  "type": "registry:block",
  "description": "A complex hello world component",
  "files": [
    // ...
  ],
  "cssVars": {
    "theme": {
      "color-brand": "var(--brand)",
      "color-brand-accent": "var(--brand-accent)"
    },
    "light": {
      "brand": "oklch(0.205 0.015 18)",
      "brand-accent": "oklch(0.205 0.015 18)"
    },
    "dark": {
      "brand": "oklch(0.205 0.015 18)",
      "brand-accent": "oklch(0.205 0.015 18)"
    }
  }
}
```

The CLI will update the project CSS file: `light` goes in the `:root` block, `dark` in `.dark`, and `theme` in `@theme inline`, the way the WebJs UI theme is laid out. Once updated, the new colors will be available to be used as utility classes: `bg-brand` and `text-brand-accent`. The `theme` entries are what make the utilities exist, since the CLI does not generate them from `light` and `dark`.

### Why does button in registryDependencies not resolve to the WebJs UI button?

A registry dependency is a name, and the CLI fetches it from the same registry as the item that lists it. In an item served from `https://acme.com/r`, `button` means `https://acme.com/r/button.json`.

Every dependency comes from the item's own registry. If your item builds on a WebJs UI component, tell users to install it first, or ship your own copy in your registry.

```bash
npx @webjsdev/ui add button
```

### How do I pin a registry item?

Put the version in the base URL. The CLI appends `/<name>.json` to whatever base it is given, so a versioned folder or a git ref in a raw URL pins every item and every dependency fetched with it.

```bash
npx @webjsdev/ui add brand-button --registry https://raw.githubusercontent.com/acme/toolkit/v1.2.0/r
```

For published registries, prefer tags or full commit SHAs. See [GitHub Registries](https://webjs.dev/ui/docs/registry/github).

### Can a registry be private?

Only by where it can be reached or by what its URL contains. The CLI sends no credentials, no custom headers and no cookies. See [Authentication](https://webjs.dev/ui/docs/registry/authentication).

### How do I add or override a Tailwind theme variable?

To add a theme variable you add it to `cssVars.theme` under the key you want to add.

```json
{
  "name": "hello-world",
  "title": "Hello World",
  "type": "registry:block",
  "description": "A complex hello world component",
  "files": [
    // ...
  ],
  "cssVars": {
    "theme": {
      "text-base": "3rem",
      "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
      "font-heading": "Poppins, sans-serif"
    }
  }
}
```

The CLI adds only the variables the project does not define yet, each in its own block, and leaves every existing one as it is. To change a value the project already sets, such as `--primary`, tell users to edit their stylesheet, or ship a `registry:file` they import after the theme.

### Why is @webjsdev/core installed when my item lists no dependencies?

`add` always installs `@webjsdev/core` along with an item's `dependencies`, since every kit file builds on it. Pass `--no-deps` to skip installing packages altogether.
