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
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:
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
Every app must have a
components.jsonfile. Apackage.jsonfile tells your package manager how to install the dependencies. Acomponents.jsonfile tells the CLI how and where to install components.The aliases in
components.jsonare directory paths relative to that app, so the defaults work unchanged in every app:
{
"$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"
}
Use the same
styleandbaseColorin 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.Tailwind CSS v4 is configured in CSS, so leave
tailwind.configout ofcomponents.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.yamlmeans pnpmyarn.lockmeans yarnbun.lockorbun.lockbmeans bunpackage-lock.jsonornpm-shrinkwrap.jsonmeans 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.