# Monorepo

Using WebJs UI components and the CLI in a monorepo.

Source: https://webjs.dev/ui/docs/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:

```bash
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**.

```bash
cd apps/web
```

```bash
npx @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:

```bash
npx @webjsdev/ui add button --cwd apps/web
```

### Importing components

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

```ts
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:

```txt
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:

```json title="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.

```bash
npx @webjsdev/ui diff --cwd apps/admin
```
