Setting Up a Project

Run miso init to set up Miso in your project.

This creates a miso.json configuration file in the current directory. Miso will try to assume its own default configuration, but will ask you to confirm during miso init to make sure you’re both on the same page.

Choosing Your Repo Type

During miso init, Miso will ask whether you’re setting up a single project or a monorepo:

? What type of repository is this?
  ❯ Single project
    Monorepo

Single Project

The default. Miso works exactly as you’d expect — one miso.json at the root, one scripts/ folder, run commands from anywhere in the project.

Monorepo

If you select Monorepo, Miso will ask for your workspace glob patterns:

? Workspace patterns
  apps/*, packages/*

This defaults to apps/*, packages/* which covers the most common monorepo layouts. Miso will:

• Add a workspaces field to your root package.json using the patterns you provide
• Create the base workspace directories (e.g. apps/, packages/)
• Write "repo": "mono" to your miso.json

Your package.json will look like:

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

And your miso.json:

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

Running Commands from Anywhere

You can run Miso commands from any subdirectory within your project. Miso walks up the directory tree to find your miso.json at the root.

my-monorepo/
├── miso.json
├── package.json
├── apps/
│   ├── onboarding/
│   │   └── scripts/
│   │       └── build.sh
│   └── web/
│       └── scripts/
│           └── build.sh
└── packages/
    └── ui/
        └── scripts/
            └── build.sh

Running Workspace Scripts from Root

In a monorepo, use workspace:script syntax to target a specific workspace’s scripts folder from anywhere:

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

Automatic Scoping from Inside a Workspace

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

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

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

Root-level Commands Still Work

Running a plain miso build from the project root resolves against the root scripts/ folder as normal — workspace scoping only activates when you’re inside a known workspace directory.