Monorepos

Miso has first-class support for monorepos. When configured, you can run workspace-scoped scripts using a clean workspace:script syntax, and Miso will automatically scope commands based on your current directory.

Setup

During miso init, select Monorepo when prompted for your repository type. Miso will ask for your workspace glob patterns and scaffold everything for you.

If you’re adding monorepo support to an existing project, make two changes:

1. Add "repo": "mono" to miso.json:


{
  "$schema": "https://misojs.dev/miso.schema.json",
  "scripts": "./scripts",
  "repo": "mono"
}

2. Add a workspaces field to your root package.json:


{
  "name": "my-monorepo",
  "packageManager": "pnpm",
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

The workspaces field uses standard glob patterns and is compatible with npm, yarn, pnpm, and bun — no extra tooling required.

Workspace Scripts

Each workspace can have its own scripts/ folder. Miso discovers and executes scripts from the correct workspace, and sets the working directory to that workspace’s root so all relative paths resolve correctly.

Folder Structure


my-monorepo/
├── miso.json
├── package.json
├── scripts/               ← root-level scripts
│   └── build.sh
├── apps/
│   ├── onboarding/
│   │   └── scripts/       ← workspace-scoped scripts
│   │       ├── build.sh
│   │       └── deploy.sh
│   └── web/
│       └── scripts/
│           ├── build.sh
│           └── dev.sh
└── packages/
    └── ui/
        └── scripts/
            └── build.sh

Running Workspace Scripts

From the Root — `workspace:script` Syntax

Target any workspace’s scripts from the project root using the workspace:script syntax:


miso onboarding:build    # runs apps/onboarding/scripts/build.sh
miso web:dev             # runs apps/web/scripts/dev.sh
miso ui:build            # runs packages/ui/scripts/build.sh

The workspace name is the final directory segment of the workspace path. For example, apps/onboarding → onboarding, packages/ui → ui.

From Inside a Workspace — Automatic Scoping

When you’re already inside a workspace directory, Miso automatically scopes to that workspace. No special syntax needed:


cd apps/onboarding
miso build    # resolves to apps/onboarding/scripts/build.sh
miso deploy   # resolves to apps/onboarding/scripts/deploy.sh

This matches the same behaviour you’d expect from tools like Turborepo’s automatic package scoping.

Root Scripts Still Work

Running a plain command from the project root resolves against the root scripts/ folder as normal. Workspace scoping only activates when you’re inside a known workspace, or when you use the workspace:script syntax.


# from project root
miso build    # runs root scripts/build.sh

Working Directory

A key benefit of workspace scripts is that the working directory is always set to the workspace root — not the project root, and not wherever you typed the command. This means relative paths in your scripts work exactly as expected:


# apps/onboarding/scripts/build.sh
# cwd is apps/onboarding/
 
bun run build            # uses apps/onboarding/package.json
cp -r dist/ ../../shared/

Resolution Order in Mono Mode

When "repo": "mono" is set, workspace script resolution is inserted before the root scripts folder:

Built-in commands
Workspace script (explicit workspace:script or CWD-based automatic scoping)
Root scripts folder
Root package.json scripts
Passthrough to package manager

If a workspace script is not found, Miso falls through to the root scripts folder and package.json as normal — nothing breaks.