Skip to content
WebJs
Menu

Using WebJs UI components and the CLI in a monorepo.

The kit copies source into the app that asks for it, so a monorepo is a set of apps that each own their components. Every WebJs app in the workspace has its own components.json, its own components/ui/ and its own theme, and the CLI installs into whichever app you point it at.

The CLI understands the workspace in one place: it reads the package manager from the workspace root, so the dependencies an item needs are installed with the tool the whole repository uses.

Getting started

Create an app in the workspace

Scaffold each app with webjs create, inside the folder your workspace keeps its apps in:

cd apps
webjs create web

The scaffold writes the app's components.json, its cn() helper and its theme, so it is ready for add. For an app that already exists, run init inside it instead.

Add components to your app

To add components, run the add command in the path of your app.

cd apps/web
pnpm dlx @webjsdev/ui add [component]

The CLI reads apps/web/components.json and writes the files under apps/web. For example, add login-01 installs the button, card, field and input components it uses into apps/web/components/ui/, and the block's own page and form into apps/web/app/login/page.ts and apps/web/components/login-form.ts.

From the workspace root, pass the app's directory with --cwd instead of changing into it:

pnpm dlx @webjsdev/ui add button --cwd apps/web

Importing components

Import the components through the app's own package imports:

import { buttonClass } from '#components/ui/button.ts';
import { cn } from '#lib/utils/cn.ts';

File Structure

A workspace with two WebJs apps looks like this:

apps
├── web           # An app.
│   ├── app
│   │   └── login
│   │       └── page.ts
│   ├── components
│   │   ├── login-form.ts
│   │   └── ui
│   │       └── button.ts
│   ├── lib
│   │   └── utils
│   │       ├── cn.ts
│   │       └── dom.ts
│   ├── styles
│   │   └── globals.css
│   ├── components.json
│   └── package.json
└── admin         # Another app, with its own copies.
    ├── components.json
    └── package.json
package.json      # The workspace root, with the lockfile.

Requirements

  1. Every app must have a components.json file. A package.json file tells your package manager how to install the dependencies. A components.json file tells the CLI how and where to install components.

  2. The aliases in components.json are directory paths relative to that app, so the defaults work unchanged in every app:

apps/web/components.json
{
  "$schema": "https://ui.webjs.dev/schema.json",
  "style": "default",
  "tailwind": {
    "css": "styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "components",
    "utils": "lib/utils/cn",
    "ui": "components/ui",
    "lib": "lib"
  },
  "iconLibrary": "lucide"
}
  1. Use the same style and baseColor in every app that should look the same. Each app bakes its own copy, so two apps with different styles look different, which is also how you give an admin app a different look.

  2. Tailwind CSS v4 is configured in CSS, so leave tailwind.config out of components.json.

By following these requirements, the CLI will install components, blocks and their helpers to the correct paths in each app and rewrite their imports for you.

Package manager

When an item needs an npm package (a Tier-2 element needs @webjsdev/core), add installs it with your package manager. It looks for a lockfile in the app's directory and then in each parent, stopping at the workspace root, which is the first directory with a pnpm-workspace.yaml or a package.json declaring workspaces. So an app inside a workspace uses the root's lockfile:

  • pnpm-lock.yaml means pnpm
  • yarn.lock means yarn
  • bun.lock or bun.lockb means bun
  • package-lock.json or npm-shrinkwrap.json means npm

With no lockfile it reads the package manager that ran the command (pnpm dlx, bunx and friends set npm_config_user_agent), and falls back to npm.

Sharing components across apps

Each app holds its own copy of each component: run init and add in every app that uses the kit.

That copy is what makes the component yours to edit in that app, and it is what a WebJs app can serve: the server serves the files in the app's own import graph, as native modules with no bundler. To keep two apps' copies in step, run diff in each app to see what changed upstream, and add the component again with --overwrite where you want the new version.

pnpm dlx @webjsdev/ui diff --cwd apps/admin