# Installation

How to install dependencies and structure your app.

Source: https://webjs.dev/ui/docs/installation

**Recommended for new projects:** Use [Create](https://webjs.dev/ui/create) to build your preset visually and get the command that applies it to your app.

WebJs UI is the component library for WebJs apps. Choose the setup that matches your starting point.

- Use Create Build your design system visually and get the command that applies it.
- Use the CLI Scaffold a new WebJs app with the kit already set up.
- Existing Project Add WebJs UI to a WebJs app you already created.
- Manual Installation Set up every file by hand.

## Use Create

Build your design system visually: pick the style, the colors, the radius, the fonts and the icons, and preview them on real components. Create prints an `init --preset` command that applies your choices to a WebJs app in one step.

[Open Create](https://webjs.dev/ui/create)

```bash
npx @webjsdev/ui init --preset <code>
```

## Use the CLI

Use the CLI to scaffold a new project directly from the terminal:

```bash
npm create webjs@latest my-app
cd my-app && npm run dev
```

A new app is ready for the kit. `webjs create` writes the same `components.json`, `lib/utils/cn.ts` and theme that `init` would.

Its colors and fonts are the theme in `styles/globals.css`, so a preset from [/ui/create](https://webjs.dev/ui/create) repaints it:

```bash
npx @webjsdev/ui init --preset b0
```

Add the components you need:

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

Inside a WebJs app, `webjs ui` runs the same commands, since `@webjsdev/ui` ships with the WebJs CLI: `webjs ui add button card dialog`.

## Existing Project

Run `init` in the app's root. It asks for a base color and the path of your Tailwind CSS file, then writes `components.json`, copies the `cn()` helper to `lib/utils/cn.ts` (with `lib/utils/dom.ts` beside it), and appends the theme tokens to the stylesheet.

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

Point it at the stylesheet your app compiles. Its default, `styles/globals.css`, is where `webjs create` puts the theme, imported from `public/input.css`, the stylesheet the app compiles. Running `init` again is safe: it keeps an existing `components.json` and helper files as they are unless you pass `--overwrite`.

Then add components:

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

The kit is copied into your app, not imported from a package at runtime. Tier-2 elements import `@webjsdev/core`, which every WebJs app already depends on, and `add` installs it when you add a Tier-2 component.

## Manual Installation

### Add Tailwind CSS

Components are styled using Tailwind CSS v4. A WebJs app made with `webjs create` already compiles `public/input.css` into `public/tailwind.css`, which its root layout links. Otherwise, [follow the Tailwind CLI installation instructions](https://tailwindcss.com/docs/installation/tailwind-cli) and compile your entry the same way.

```bash
npm install tailwindcss @tailwindcss/cli
```

### Add dependencies

The kit has one runtime dependency, `@webjsdev/core`, which the Tier-2 elements extend. A WebJs app already has it.

```bash
npm install @webjsdev/core
```

### Configure import aliases

WebJs apps use the `imports` field of `package.json` for their aliases. Node and Bun resolve it at runtime with no build step and no `tsconfig.json` paths.

```json title="package.json"
{
  "imports": {
    "#*": "./*"
  }
}
```

That one entry makes every top-level folder an alias: `#components/ui/button.ts`, `#lib/utils/cn.ts`. See the [package imports guide](https://webjs.dev/ui/docs/package-imports) for the details.

### Configure styles

Add the following to the stylesheet your app compiles, after `@import "tailwindcss";`. You can learn more about using CSS variables for theming in the [theming section](https://webjs.dev/ui/docs/theming).

```css title="public/input.css"
@import "tailwindcss";

/* @webjsdev/ui theme */
/* Generated by `webjsui init`. Edit freely - you own this. */

@theme inline {
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

/* Custom variants for component data attributes */
@custom-variant data-open (&:where([data-state="open"]));
@custom-variant data-closed (&:where([data-state="closed"]));
@custom-variant data-checked (&:where([data-state="checked"]));
@custom-variant data-unchecked (&:where([data-state="unchecked"]));
@custom-variant data-active (&:where([data-state="active"]));
@custom-variant data-disabled (&:where([data-disabled]:not([data-disabled="false"])));
@custom-variant data-selected (&:where([data-selected="true"]));
@custom-variant data-horizontal (&:where([data-orientation="horizontal"]));
@custom-variant data-vertical (&:where([data-orientation="vertical"]));
@custom-variant dark (&:is(.dark *));

@keyframes accordion-down {
  from { height: 0; }
  to { height: var(--accordion-panel-height, auto); }
}
@keyframes accordion-up {
  from { height: var(--accordion-panel-height, auto); }
  to { height: 0; }
}

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.97 0.01 17);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.81 0.10 252);
  --chart-2: oklch(0.62 0.19 260);
  --chart-3: oklch(0.55 0.22 263);
  --chart-4: oklch(0.49 0.22 264);
  --chart-5: oklch(0.42 0.18 265);
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.371 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --destructive-foreground: oklch(0.58 0.22 27);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
  --chart-1: oklch(0.81 0.10 252);
  --chart-2: oklch(0.62 0.19 260);
  --chart-3: oklch(0.55 0.22 263);
  --chart-4: oklch(0.49 0.22 264);
  --chart-5: oklch(0.42 0.18 265);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.439 0 0);
}

@layer base {
  /* Focus: a themed, keyboard-only (:focus-visible), never-removed outline, in
     the --ring colour, applied globally. `outline-ring/50` themes only the
     COLOUR and leaves outline-style: auto, which the browser draws as its OWN
     ring (it can look thick/white and ignore the colour). So force a SOLID
     outline on focus, at a consistent width + offset, so the themed --ring/50
     colour actually renders the same on every element. A shadow-DOM component
     sets its own focus (a document rule cannot cross the shadow boundary). */
  * {
    @apply border-border outline-ring/50;
  }
  :focus-visible {
    outline: 2px solid color-mix(in oklab, var(--color-ring) 50%, transparent);
    outline-offset: 2px;
  }
  /* Native <select> options paint transparent over the browser popup when no
     rule applies, so in dark mode Chrome's dark popup plus the inherited text
     colour makes every unselected option disappear. Canvas / CanvasText are
     the system colours the browser would have painted anyway, so this stops
     relying on inheritance to pull them through. Two ELEMENT selectors
     (specificity 0,0,2) and no wrapper requirement on purpose: a bare
     <select class=${nativeSelectClass()}> with no wrapper is legitimate, and
     any single class overrides this. */
  select option,
  select optgroup {
    background-color: Canvas;
    color: CanvasText;
  }
}

/* @webjsdev/ui theme end */
```

### Add a cn helper

Components merge their classes with `cn()`, a small hand-written class merger in place of clsx and tailwind-merge, plus `onBeforeCache()`, a client-only helper kept in its own file. Print each one and save its source, the lines after the `# lib/...` header, under `lib/utils/`:

```bash
npx @webjsdev/ui view lib-utils --source
```

```bash
npx @webjsdev/ui view lib-dom --source
```

Save the first as `lib/utils/cn.ts` and the second as `lib/utils/dom.ts`, beside it. The components import `dom.ts` as the sibling of the `cn()` file, so keep the two together.

### Create a components.json file

Create a `components.json` file in the root of your project.

```json title="components.json"
{
  "$schema": "https://ui.webjs.dev/schema.json",
  "style": "default",
  "tailwind": {
    "css": "public/input.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "components",
    "utils": "lib/utils/cn",
    "ui": "components/ui",
    "lib": "lib"
  }
}
```

The aliases are folders relative to the project root, and `utils` names the `cn()` file without its extension. See [components.json](https://webjs.dev/ui/docs/components-json) for every key.

### That's it

You can now start adding components to your project.

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