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

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.

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, which instructs pnpm which directories contain packages that should be linked together.

# 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

All internal dependencies are expressed with the workspace:* protocol in the root package.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):

npm i -g pnpm@10

2. Clone the repository and navigate to the root:

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

3. Install all workspace packages – pnpm automatically reads pnpm-workspace.yaml and creates symlinks:

pnpm install

4. Build workspace packages – The root package.json provides a postinstall script that automatically builds each package in the correct dependency order:

pnpm run build

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

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:

pnpm --filter @openmaic/renderer run dev

To execute arbitrary commands within a specific package context:

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 guarantees that all @openmaic/* packages resolve to their local counterparts within the monorepo. When you import from another workspace package:

// 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
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, including packages/* and packages/@openmaic/* while excluding packages/docs
• Internal packages use the workspace:* protocol in the root 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

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 because it functions as a standalone Next.js application with its own lockfile (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}