# Configuring a monorepo using workspaces (/docs/guides/install/workspaces)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 482 · updated: 2026-07-28 -->
Related: [Add a dependency](/docs/guides/install/add.md), [Add a development dependency](/docs/guides/install/add-dev.md), [Add an optional dependency](/docs/guides/install/add-optional.md), [Add a peer dependency](/docs/guides/install/add-peer.md), [Add a Git dependency](/docs/guides/install/add-git.md), [Add a tarball dependency](/docs/guides/install/add-tarball.md)

Bun's package manager supports npm `"workspaces"`. Workspaces split a codebase into distinct packages that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.

Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.

***

The root `package.json` should not contain `"dependencies"`, `"devDependencies"`, or other dependency fields. Each package should be self-contained and declare its own dependencies. It's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.

```json package.json icon="file-json"
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["packages/*"]
}
```

***

It's common to place all packages in a `packages` directory. The `"workspaces"` field in `package.json` supports glob patterns, so `packages/*` treats each subdirectory of `packages` as a separate *package* (also known as a workspace).

```txt File Tree icon="folder-tree"
.
├── package.json
├── node_modules
└── packages
    ├── stuff-a
    │   └── package.json
    └── stuff-b
        └── package.json
```

***

To add dependencies between workspaces, use the `"workspace:*"` syntax. The following adds `stuff-a` as a dependency of `stuff-b`.

```json packages/stuff-b/package.json icon="file-json"
{
  "name": "stuff-b",
  "dependencies": {
    "stuff-a": "workspace:*" // [!code ++]
  }
}
```

***

Once added, run `bun install` from the project root to install dependencies for all workspaces.

```sh terminal icon="terminal"
bun install
```

***

To add npm dependencies to a particular workspace, `cd` to that directory and run `bun add` as you normally would. Bun detects that you are in a workspace and [hoists](/pm/isolated-installs) the dependency as needed.

```sh terminal icon="terminal"
cd packages/stuff-a
bun add zod
```

***

See [`bun install`](/pm/cli/install).