# How to Set Up the OpenMAIC Monorepo with pnpm Workspaces: A Complete Guide

> Learn to set up the OpenMAIC monorepo with pnpm workspaces. Follow this guide to install dependencies, clone the repo, and link packages for seamless development.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Setting up the OpenMAIC monorepo requires installing pnpm (≥10.28.0), cloning the THU-MAIC/OpenMAIC repository, and running `pnpm install` at the root to symlink all workspace packages defined in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml).**

The OpenMAIC project by THU-MAIC is organized as a **pnpm workspace monorepo**, enabling efficient dependency management across multiple interconnected packages. This architecture allows developers to work on isolated modules while maintaining seamless internal linking through the `workspace:*` protocol. Understanding the workspace configuration and setup commands ensures you can immediately begin developing the DSL, editor, generation, importer, renderer, and storage packages.

## Understanding the Workspace Configuration

The workspace definition lives in the root file **[`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml)**, which instructs pnpm which directories contain packages that should be linked together.

```yaml

# pnpm-workspace.yaml

packages:
  - "packages/*"
  - "packages/@openmaic/*"
  - "!packages/docs"   # docs is a standalone app with its own lockfile

```

This configuration includes:

- **`packages/*`** – All first-level packages under `packages/`
- **`packages/@openmaic/*`** – Scoped packages under the `@openmaic` namespace
- **`!packages/docs`** – The documentation site is explicitly excluded because it maintains its own lockfile and build pipeline at [`packages/docs/pnpm-lock.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/docs/pnpm-lock.yaml)

All internal dependencies are expressed with the **`workspace:*`** protocol in the root **[`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json)**:

```json
"@openmaic/dsl": "workspace:*",
"@openmaic/editor": "workspace:*",
"@openmaic/generation": "workspace:*",
"@openmaic/importer": "workspace:*",
"@openmaic/renderer": "workspace:*",
"@openmaic/storage": "workspace:*"

```

## Step-by-Step Setup Instructions

To configure your local development environment:

1. **Install pnpm** globally (version 10.28.0 or higher required):

```bash
npm i -g pnpm@10

```

2. **Clone the repository** and navigate to the root:

```bash
git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC

```

3. **Install all workspace packages** – pnpm automatically reads [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) and creates symlinks:

```bash
pnpm install

```

4. **Build workspace packages** – The root [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) provides a `postinstall` script that automatically builds each package in the correct dependency order:

```bash
pnpm run build

```

5. **Start the documentation site** – Since `packages/docs` is excluded from the workspace, it requires separate installation:

```bash
cd packages/docs
pnpm install
pnpm dev  # Available at http://localhost:3000

```

## Working with Workspace Packages

The **`pnpm --filter`** command allows you to target specific packages without reinstalling the entire monorepo.

To run a specific workspace package in development mode:

```bash
pnpm --filter @openmaic/renderer run dev

```

To execute arbitrary commands within a specific package context:

```bash
pnpm --filter @openmaic/generation exec <command>

```

These commands respect workspace links, ensuring internal imports resolve to local source code rather than registry versions.

## Managing Dependencies with workspace:*

The **`workspace:*`** protocol in [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) guarantees that all `@openmaic/*` packages resolve to their local counterparts within the monorepo. When you import from another workspace package:

```tsx
// Inside any @openmaic package
import { render } from '@openmaic/renderer';

```

pnpm resolves this to the local source in `packages/@openmaic/renderer/`, ensuring you always work with the latest changes without publishing to npm.

## Adding New Packages to the Monorepo

To extend the OpenMAIC monorepo with a new internal package:

1. Create the folder structure at `packages/@openmaic/<new-pkg>` with its own [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json)
2. Register the package name in the **`OPENMAIC_PACKAGES`** array within **`scripts/openmaic-packages.mjs`** to maintain CI synchronization
3. Run `pnpm install` at the root – pnpm automatically detects and links the new workspace package

## Summary

- The workspace configuration resides in **[`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml)**, including `packages/*` and `packages/@openmaic/*` while excluding `packages/docs`
- Internal packages use the **`workspace:*`** protocol in the root [`package.json`](https://github.com/THU-MAIC/OpenMAIC/blob/main/package.json) for zero-latency local development
- Use **`pnpm --filter @openmaic/<package>`** to run commands on specific packages without full installs
- The **`scripts/openmaic-packages.mjs`** file serves as the single source of truth for package registration in CI pipelines
- The documentation site operates independently with its own lockfile at [`packages/docs/pnpm-lock.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/docs/pnpm-lock.yaml)

## Frequently Asked Questions

### What version of pnpm is required for OpenMAIC?

OpenMAIC requires **pnpm version 10.28.0 or higher**. Install it globally with `npm i -g pnpm@10` before cloning the repository to ensure compatibility with the workspace configuration and lockfile format.

### Why is the docs package excluded from the workspace?

The **`packages/docs`** directory is excluded via `!packages/docs` in [`pnpm-workspace.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/pnpm-workspace.yaml) because it functions as a standalone Next.js application with its own lockfile ([`packages/docs/pnpm-lock.yaml`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/docs/pnpm-lock.yaml)) and build pipeline. This isolation prevents dependency conflicts between the documentation site's specific requirements and the core workspace packages.

### How do I run only one package without installing the entire monorepo?

Use **pnpm's filter flag**: `pnpm --filter @openmaic/<package-name> run <script>`. For example, `pnpm --filter @openmaic/editor run dev` starts only the editor package. This command respects workspace links, so the filtered package still resolves local dependencies from the monorepo without requiring separate installations.

### Where is the list of valid @openmaic packages defined?

The authoritative list lives in **`scripts/openmaic-packages.mjs`**, which exports an `OPENMAIC_PACKAGES` array. This module serves as the single source of truth for CI checks and build scripts. When adding a new package to `packages/@openmaic/`, you must update this array to ensure the package is included in automated builds and validation workflows.