Skip to content
WebJs
Menu

Installation

How to install dependencies and structure your app.

Recommended for new projects: Use 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: 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
pnpm dlx @webjsdev/ui init --preset <code>

Use the CLI

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

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 repaints it:

pnpm dlx @webjsdev/ui init --preset b0

Add the components you need:

pnpm dlx @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.

pnpm dlx @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:

pnpm dlx @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 and compile your entry the same way.

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.

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.

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

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/:

pnpm dlx @webjsdev/ui view lib-utils --source
pnpm dlx @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.

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 for every key.

That's it

You can now start adding components to your project.

pnpm dlx @webjsdev/ui add button