# components.json

Configuration for your project.

Source: https://webjs.dev/ui/docs/components-json

The `components.json` file holds configuration for your project.

The CLI uses it to understand how your project is set up and how to write components customized for your project.

Note: The components.json file is optional

It is **only required if you're using the CLI** to add components to your project. If you're using the copy and paste method, you don't need this file.

You can create a `components.json` file in your project by running the following command:

```bash
npx @webjsdev/ui init
```

Inside a WebJs app the same command is `webjs ui init`, and an app made with `webjs create` already has the file. See the [CLI section](https://webjs.dev/ui/docs/cli) for more information.

## $schema

`init` writes the following `$schema` value. The CLI does not fetch it: it validates the file against its own schema, which is strict, so a key it does not know is an error rather than a silent no-op.

```json title="components.json"
{
  "$schema": "https://ui.webjs.dev/schema.json"
}
```

## style

The style for your components. The kit authors every component once, with semantic `cn-*` class names, and `add` bakes the chosen style into the file it writes, so the copy in your project holds plain Tailwind classes.

```json title="components.json"
{
  "style": "new-york"
}
```

The styles are `new-york`, `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera` and `rhea`. `init` writes `"default"`, which means `new-york`, and so does a name the kit does not ship. `init --style <name>`, or a preset from [Create](https://webjs.dev/ui/create) (`init --preset <code>`), writes another.

The style is read each time you run `add`, so changing it later affects only the components you add afterwards. The ones already in your project keep the classes they were baked with until you add them again with `--overwrite`, and `diff` reports them as out of date in the meantime.

## tailwind

Configuration to help the CLI understand how Tailwind CSS is set up in your project.

See the [installation section](https://webjs.dev/ui/docs/installation) for how to set up Tailwind CSS.

### tailwind.config

The kit targets Tailwind CSS v4, which is configured in CSS. The key is accepted so an older config still parses. **Leave it out.**

### tailwind.css

Path to the CSS file that imports Tailwind CSS into your project. `init` appends the theme tokens to it, and `add` writes the tokens back if they go missing and merges in the CSS variables a component or block carries.

```json title="components.json"
{
  "tailwind": {
    "css": "styles/globals.css"
  }
}
```

The default is `styles/globals.css`, not `app/globals.css`, because in a WebJs app the `app/` directory holds routes only. `init --css <path>` points it somewhere else.

### tailwind.baseColor

This is used to generate the default theme tokens for your components.

```json title="components.json"
{
  "tailwind": {
    "baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe"
  }
}
```

The tokens are written once. `init` marks where the theme block it appends starts and ends, and a later plain run, or an `add`, leaves the block as it is. Changing `baseColor` in this file therefore does not repaint an existing project. To repaint it, run `init --base-color <name> --overwrite` or `init --preset <code>`, which replace the marked block in place (`--overwrite` also resets the aliases and the helper files), or edit the variables by hand. A block written before the end marker existed is never replaced, only reported. See the [theming docs](https://webjs.dev/ui/docs/theming).

### tailwind.cssVariables

The kit uses CSS variables for theming, and only CSS variables. Every component is written against semantic tokens like `background`, `foreground` and `primary`.

```json title="components.json"
{
  "tailwind": {
    "cssVariables": true
  }
}
```

`init` writes `true`, which the components are built for: their classes name the theme tokens. For more information, see the [theming docs](https://webjs.dev/ui/docs/theming).

### tailwind.prefix

A component lands with Tailwind's unprefixed utilities, so leave the prefix empty.

## rsc

A page renders on the server, and a component that needs JavaScript ships it on its own, with nothing to mark. Leave `rsc` out of `components.json`: the config schema is strict, so an unknown key is an error.

## tsx

The kit ships TypeScript sources, so leave `tsx` out of `components.json`. WebJs strips the types when it serves a file, with no build step, so a JavaScript app imports the `.ts` files as they are. See [JavaScript](https://webjs.dev/ui/docs/javascript).

## aliases

The CLI uses these values to place the files it writes. Each one is a **directory path** relative to the project root, not an import specifier. A leading `@/` is accepted and dropped.

Inside the files it writes, the CLI rewrites every registry import to a relative path that resolves from where the file landed, so `components/ui/dialog.ts` imports `../../lib/utils/cn.ts` and `./button.ts`. Relative imports need no alias configuration at all, which is why the aliases here are plain paths.

Important

Your own code imports the installed files through the app's `#` package import, for example `#components/ui/button.ts`. That comes from `package.json`, not from `components.json`. Do not write `#components` as an alias value here: it is read as a directory named `#components`. See [Package Imports](https://webjs.dev/ui/docs/package-imports).

```json title="components.json"
{
  "aliases": {
    "components": "components",
    "utils": "lib/utils/cn",
    "ui": "components/ui",
    "lib": "lib"
  }
}
```

These are the values `init` and `webjs create` both write, so a scaffolded app and an app that ran `init` share one layout.

For monorepos, see the [monorepo docs](https://webjs.dev/ui/docs/monorepo).

### aliases.utils

The path of your `cn()` helper, without the extension. `lib/utils/cn` is the file `lib/utils/cn.ts`. The client-only `onBeforeCache()` helper is written beside it, as `lib/utils/dom.ts`.

```json title="components.json"
{
  "aliases": {
    "utils": "lib/utils/cn"
  }
}
```

Both helpers are yours once they exist: `init` and `add` leave an existing copy alone, and only `--overwrite` replaces it.

### aliases.components

The directory for your components.

```json title="components.json"
{
  "aliases": {
    "components": "components"
  }
}
```

### aliases.ui

The directory for `ui` components.

The CLI uses the `aliases.ui` value to determine where to place your `ui` components. Use this config if you want to customize the installation directory for your `ui` components.

```json title="components.json"
{
  "aliases": {
    "ui": "modules/design/ui"
  }
}
```

### aliases.lib

The directory for `lib` files that a registry item installs.

```json title="components.json"
{
  "aliases": {
    "lib": "lib"
  }
}
```

### aliases.hooks

WebJs components keep state in signals and reactive properties. Reusable component logic, such as a reactive controller, ships as a `registry:hook` file and lands in `hooks/`.

## iconLibrary

The icon library the components and blocks draw with: `lucide` (the default), `tabler`, `hugeicons`, `phosphor` or `remixicon`. The icons are inline SVG, so no icon package is installed. An item that draws icons depends on the kit's icon module, and `add` installs the one for this library at `lib/utils/icons.ts`, beside `cn.ts`. `init --icons <library>`, or a preset, sets the key and writes that file.

```json title="components.json"
{
  "iconLibrary": "lucide"
}
```

## lint

The opt-in design-system linter, `webjs ui lint`, reads its configuration from here. With no `lint` block it reports nothing and exits 0.

```json title="components.json"
{
  "lint": {
    "ignore": ["app/legacy/**"],
    "rules": {
      "no-raw-colors": "warn",
      "no-arbitrary-values": { "severity": "warn", "allow": ["layout"] },
      "no-restyle": { "severity": "error", "allow": ["layout", "rounded"] }
    }
  }
}
```

A rule is a bare severity (`"off"`, `"warn"` or `"error"`) or an object adding `allow`, which takes a category name or a class group. A rule left out is off. See the [CLI](https://webjs.dev/ui/docs/cli) for the command.

## registries

To install from a registry other than the kit's own, pass its base URL with `--registry`:

```bash
npx @webjsdev/ui add button --registry https://registry.example.com
```

See the [Registry](https://webjs.dev/ui/docs/registry) documentation for building and hosting one.
