Skip to content
WebJs
Menu

Use the WebJs UI CLI to add components and blocks to your project.

The CLI ships in the @webjsdev/ui package as the webjsui binary. Run it with npx @webjsdev/ui <command> from any package manager, or as webjs ui <command> inside a WebJs app, since @webjsdev/ui is a dependency of the WebJs CLI and webjs ui passes its arguments straight through.

init, add, list and view read the registry that ships inside the installed package, so they need no network. Only diff, and a custom registry passed with --registry, go to the network.

init

Use the init command to initialize configuration and dependencies for an existing WebJs app. An app created with webjs create is already initialized.

The init command writes components.json, adds the cn util at lib/utils/cn.ts (with lib/utils/dom.ts beside it) and appends the theme's CSS variables to your stylesheet, styles/globals.css by default.

pnpm dlx @webjsdev/ui init

Options

Usage: webjsui init [options]

Initialize @webjsdev/ui in a project: writes components.json, theme CSS,
lib/utils/cn.ts

Options:
  -c, --cwd <cwd>       the working directory (default: the current directory)
  -y, --yes             skip confirmation prompts (default: false)
  --base-color <color>  base color (neutral|stone|zinc|mauve|olive|mist|taupe)
  --css <path>          path to the project Tailwind CSS file
  -o, --overwrite       replace an existing alias map, existing helper files and
                        the theme block (default: false)
  --preset <code>       apply a design-system preset code from
                        webjs.dev/ui/create (style, colors, font, radius, icons)
  --style <name>        component style
                        (new-york|vega|nova|maia|lyra|mira|luma|sera|rhea)
  --icons <library>     icon library
                        (lucide|tabler|hugeicons|phosphor|remixicon)
  --registry <url>      registry base URL (default:
                        "https://webjs.dev/ui/registry")
  -h, --help            display help for command

To start from a design system, build one in Create and pass the code it prints. A preset sets the style, the colors, the radius, the fonts and the icon library in one go: it writes them to components.json, replaces the theme block in your stylesheet with the preset's tokens, writes the chosen icon library to lib/utils/icons.ts, and prints the stylesheet URL for the preset's fonts, which you load yourself. --style and --icons set one of those on their own, and also override what a preset names.

pnpm dlx @webjsdev/ui init --preset <code>

A style or icon library applies to what add writes from then on. Components you added before keep the classes they were baked with until you add them again with --overwrite.

Running init again is safe. An existing components.json keeps its aliases, stylesheet path and base color, and an existing cn.ts or dom.ts is left as you edited it. Pass --overwrite to reset them, the theme block included. A theme block written before the kit marked where it ends is never replaced, only reported, since init cannot tell where it stops. The command exits with an error when it cannot write the theme tokens, so a clean exit means the components are styled.


add

Use the add command to add components, blocks and their dependencies to your project.

pnpm dlx @webjsdev/ui add [component]

It resolves each item's registry dependencies transitively, copies the source into your components/ui alias, installs any npm dependency your package.json does not already declare with your project's package manager, and puts back the theme tokens if they are missing. A block's files land at their own targets under the app. See Blocks.

Options

Usage: webjsui add [options] [components...]

Add one or more components to your project

Arguments:
  components        component names (e.g. button card dialog)

Options:
  -c, --cwd <cwd>   the working directory (default: the current directory)
  -y, --yes         skip overwrite prompts (default: false)
  -o, --overwrite   overwrite existing files without asking (default: false)
  --no-deps         skip installing npm dependencies
  --registry <url>  registry base URL (default: "https://webjs.dev/ui/registry")
  -h, --help        display help for command

For a class-helper component, add copies the helpers and leaves the worked example out of the file, with a one-line pointer to npx @webjsdev/ui view <name>, which prints it. The shared cn.ts and dom.ts helpers, and every file a block writes, are yours once they exist: add replaces one only with --overwrite, and --yes alone does not.


view

Use the view command to view items from the registry before installing them.

pnpm dlx @webjsdev/ui view [item]

For a component it prints the projected view (the helpers with their signatures, the accessibility notes and the paste-ready example) followed by the full source. For a block it prints the description, the categories, the dependencies, the install command and every file with the path it lands at, then the sources.

pnpm dlx @webjsdev/ui view login-03 --files-only

Sources are printed baked with the style named in components.json, or new-york when it names none. Pass --style to see another one.

Options

Usage: webjsui view [options] <name>

Print a registry item's source (and the paste-ready example) to stdout

Arguments:
  name              component, block or chart name

Options:
  --registry <url>  registry base URL (default: "https://webjs.dev/ui/registry")
  --source          print only the raw source, not the projected view
  --style <name>    the style to bake the source with (default: components.json,
                    else new-york)
  --json            a block or chart: print the projection as one JSON document
  --files-only      a block or chart: print the file list and stop before the
                    sources
  -h, --help        display help for command

Use the search command to search for items in the registry.

pnpm dlx @webjsdev/ui search [filter]

The filter matches a substring of the name:

pnpm dlx @webjsdev/ui search menu

Or narrow the list to one kind of item, or to one category of blocks:

pnpm dlx @webjsdev/ui search --type block --category login

The list command is an alias for search:

pnpm dlx @webjsdev/ui list --type block

Without --type it prints the components, blocks and charts in three labelled groups. --json prints one compact array of { name, type, categories, description } and nothing else, for a script or an agent.

Options

Usage: webjsui list|search [options] [filter]

List the components, blocks and charts in the registry

Arguments:
  filter             filter by substring of the name

Options:
  --type <type>      ui, block, chart or all (ui | block | chart | all)
                     (default: "all")
  --category <name>  only blocks and charts in this category (e.g. login,
                     sidebar, area)
  --json             print one compact JSON array of { name, type, categories,
                     description }
  --registry <url>   registry base URL (default:
                     "https://webjs.dev/ui/registry")
  -h, --help         display help for command

build

Use the build command to generate the registry JSON files.

pnpm dlx @webjsdev/ui build

This command reads the registry.json file, inlines each file's content into its item and writes one <name>.json per item to the r directory, plus an index.json and a copy of the manifest. Serve that directory and pass its URL to --registry. See Registry.

Options

Usage: webjsui build [options] [file]

Build a custom registry: read registry.json, inline file contents, emit r/*.json

Arguments:
  file                registry manifest path (default: "registry.json")

Options:
  -o, --output <dir>  output directory (default: "./r")
  -c, --cwd <cwd>     the working directory (default: the current directory)
  -h, --help          display help for command

To customize the output directory, use the --output option.

pnpm dlx @webjsdev/ui build --output ./public/r

diff

Use the diff command to check your local copies against the registry.

pnpm dlx @webjsdev/ui diff [component]

Components are copied into your app, so an upgrade of the kit does not change them. diff is how you find the drift. It compares each file against the live registry, transformed exactly as add would write it, so an untouched install reports nothing. Installed blocks are included. With no name it lists every item that is out of date.

Options

Usage: webjsui diff [options] [name]

Show differences between local components or blocks and the registry

Arguments:
  name              component or block to diff (omit to show all out-of-date)

Options:
  -c, --cwd <cwd>   the working directory (default: the current directory)
  --registry <url>  registry base URL (default: "https://webjs.dev/ui/registry")
  -h, --help        display help for command

info

Use the info command to get information about your project.

pnpm dlx @webjsdev/ui info

It prints the working directory, the registry URL, the kit's component, block and chart counts, and whether a components.json was found. When one was, it adds the base color, the stylesheet path and the aliases it resolved.

Options

Usage: webjsui info [options]

Print project diagnostics (config, registry)

Options:
  -c, --cwd <cwd>  the working directory (default: the current directory)
  -h, --help       display help for command

lint

Use the lint command to check your app against its design system.

pnpm dlx @webjsdev/ui lint

It reads the classes in your html templates, cn() calls and class=${...} holes and reports, at the line, a raw palette color where your theme declares a token (no-raw-colors), an arbitrary value such as p-[13px] (no-arbitrary-values), and a class composed over a kit helper (no-restyle). Each message names the alternative from your own theme tokens and helper variants.

The linter is opt-in. It reports nothing and exits 0 until components.json carries a lint block:

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"] }
    }
  }
}

It exits 1 on an error, on more warnings than --max-warnings allows, or on a config it cannot run against.

Options

Usage: webjsui lint [options]

Check the app against its design system (opt-in, configured in components.json)

Options:
  -c, --cwd <cwd>     the working directory (default: the current directory)
  --json              emit structured violations for an agent loop
  --max-warnings <n>  fail when warnings exceed this count (default: "-1")
  -h, --help          display help for command