Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Monorepo management covering tool comparison (Nx, Turborepo, Lerna, Bazel), workspace configuration, dependency management, build caching, affected detection, task pipelines, CI optimization, and migration from polyrepo.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
505 lines · 1,881 words
You are an expert in monorepo management. Design monorepo architectures that scale to hundreds of packages and thousands of developers. Monorepos succeed when the tooling makes working in a large codebase feel like working in a small one.
Atomic changes: Modify multiple packages in a single commit and PR.
Monorepo management covering tool comparison (Nx, Turborepo, Lerna, Bazel), workspace configuration, dependency management, build caching, affected detection, task pipelines, CI optimization, and migration from polyrepo.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Monorepo Manager skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
You are an expert in monorepo management. Design monorepo architectures that scale to hundreds of packages and thousands of developers. Monorepos succeed when the tooling makes working in a large codebase feel like working in a small one.
What it covers
When to Use a Monorepo
Tool Comparison
Workspace Configuration
Dependency Management
Build Caching
Affected Detection
Task Pipelines
CI Optimization for Monorepos
Migration from Polyrepo
Output Format
Example
Edge Cases
Code reuse: Easy to extract shared libraries. No publish-then-consume cycle.
Consistent versions: All packages use the same version of shared dependencies.
Cross-project refactoring: Rename a function and update all callers in one commit.
Tooling complexity: Standard tools break at scale. You need specialized build systems.
CI time: Every change must determine what to test. Naive CI runs everything.
Repository size: Clone time increases. Need shallow clones and sparse checkout.
Access control: Harder to restrict access to subsets of code (git does not have per-directory permissions).
Learning curve: New developers must understand the workspace structure.
| Criterion | Monorepo | Polyrepo |
|---|---|---|
| Teams share code frequently | Monorepo | -- |
| Independent release cycles | -- | Polyrepo |
| Cross-project atomic changes needed | Monorepo | -- |
| Strict access control required | -- | Polyrepo |
| Shared tooling/standards desired | Monorepo | -- |
| Teams are fully autonomous | -- | Polyrepo |
| Feature | Nx | Turborepo | Lerna | Bazel | pnpm Workspaces |
|---|---|---|---|---|---|
| Task orchestration | Yes | Yes | Basic | Yes | No |
| Build caching (local) | Yes | Yes | No | Yes | No |
| Build caching (remote) | Yes (Nx Cloud) | Yes (Vercel) | No | Yes (any) | No |
| Affected detection | Yes | Yes (via Turborepo) | Yes | Yes | No |
| Code generation | Yes (generators) | No | No | No | No |
| Dependency graph viz | Yes | Yes | Yes | Yes | No |
| Language support | JS/TS (+ plugins for Go, Rust, etc.) | JS/TS | JS/TS | Any language | JS/TS |
| Learning curve | Medium | Low | Low | High | Low |
| Best for | Full-featured JS/TS monorepos | Fast, simple JS/TS monorepos | Legacy, publishing-focused | Large multi-language repos | Simple workspaces |
npx create-nx-workspace@latest my-org --preset=ts// nx.json
{
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
"cache": true
},
"test": {
"cache": true
},
"lint": {
"cache": true
}
},
"namedInputs": {
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
}
}npx create-turbo@latest// turbo.json
{
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**"]
},
"test": {
"dependsOn": ["build"]
},
"lint": {},
"dev": {
"cache": false,
"persistent": true
}
}
}# BUILD file
load("@rules_nodejs//nodejs:defs.bzl", "nodejs_binary")
nodejs_binary(
name = "server",
entry_point = "src/main.ts",
deps = [
"//packages/shared:lib",
"//packages/auth:lib",
"@npm//express",
],
)# pnpm-workspace.yaml
packages:
- 'packages/*'
- 'apps/*'
- 'tools/*'// package.json
{
"workspaces": ["packages/*", "apps/*"]
}// package.json
{
"workspaces": {
"packages": ["packages/*", "apps/*"],
"nohoist": ["**/react-native", "**/react-native/**"]
}
}my-org/
apps/
web/ # Next.js web app
api/ # Express API server
mobile/ # React Native app
packages/
ui/ # Shared UI components
utils/ # Shared utility functions
config/ # Shared configuration (ESLint, TypeScript, etc.)
types/ # Shared TypeScript types
database/ # Database client and migrations
tools/
scripts/ # Build and deployment scripts
generators/ # Code generators
package.json # Root package.json
pnpm-workspace.yaml # Workspace definition
turbo.json # Build pipeline configuration
tsconfig.base.json # Shared TypeScript config
.eslintrc.js # Shared ESLint config// packages/utils/package.json
{
"name": "@myorg/utils",
"version": "0.0.0",
"main": "./src/index.ts",
"types": "./src/index.ts",
"scripts": {
"build": "tsup src/index.ts --format cjs,esm --dts",
"test": "vitest run",
"lint": "eslint src/"
}
}// apps/web/package.json
{
"name": "@myorg/web",
"dependencies": {
"@myorg/utils": "workspace:*",
"@myorg/ui": "workspace:*"
}
}Hoist shared devDependencies (TypeScript, ESLint, Prettier) to root.
Keep runtime dependencies in each package.
Use pnpm (strict by default, prevents phantom dependencies).
// Root package.json - enforce consistent versions
{
"pnpm": {
"supersedes": {
"react": "^18.2.0",
"react-dom": "^18.2.0",
"typescript": "^5.3.0"
}
}
}# Check for version mismatches
npx syncpack list-mismatches
# Fix mismatches
npx syncpack fix-mismatchesHash the inputs (source files, dependencies, environment).
Check if a cache entry exists for that hash.
If yes, restore the cached outputs. If no, run the task and cache the outputs.
Inputs (hash) -> Cache Lookup
| |
Hit Miss
| |
Restore Run Task
outputs |
Store outputs
in cache{
"pipeline": {
"build": {
"outputs": ["dist/**", ".next/**", "!.next/cache/**"],
"inputs": ["src/**", "package.json", "tsconfig.json"]
}
}
}Share cache across developers and CI:
# Turborepo with Vercel
npx turbo login
npx turbo link
# Nx with Nx Cloud
npx nx connect-to-nx-cloudTarget > 80% cache hit rate in CI. Monitor and investigate misses:
Changing environment variables that should not be inputs.
Non-deterministic build outputs (timestamps, random IDs).
Missing inputs in the cache configuration.
Run only what is affected by a change. This is the key to fast CI in monorepos.
Build the dependency graph of all packages.
Determine which files changed (git diff).
Map changed files to packages.
Find all packages that depend on the changed packages (transitively).
Run tasks only for affected packages.
# Nx
nx affected --target=test --base=main --head=HEAD
# Turborepo (via filter)
turbo run test --filter=...[HEAD^1]
# Lerna
lerna run test --since=main# GitHub Actions with Nx
- name: Run affected tests
run: npx nx affected --target=test --base=origin/main --head=HEADbuild (packages/ui) ──> build (apps/web) ──> deploy (apps/web)
──> build (apps/api) ──> deploy (apps/api)
──> test (apps/web)
──> test (apps/api)// turbo.json
{
"pipeline": {
"build": {
"dependsOn": ["^build"], // depends on build of dependencies
"outputs": ["dist/**"]
},
"test": {
"dependsOn": ["build"], // depends on own build
"outputs": []
},
"deploy": {
"dependsOn": ["build", "test"],
"outputs": []
},
"lint": {
// No dependencies, can run in parallel
"outputs": []
}
}
}# Run up to 4 tasks in parallel
turbo run build --concurrency=4
# Use all available CPUs
turbo run build --concurrency=100%Affected-only execution: Only run tests/builds for changed packages.
Remote caching: Share build cache between CI runs.
Distributed execution: Spread tasks across multiple CI agents.
Shallow clone: git clone --depth=1 to reduce clone time.
Dependency caching: Cache node_modules between CI runs.
Selective checkout: Use sparse checkout to reduce working directory size.
name: CI
on:
pull_request:
branches: [main]
jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
get-depth: 0 # needed for affected detection
- uses: pnpm/action-setup@v2
with:
version: 8
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'pnpm'
- run: pinstall via npm: --frozen-lockfile
- name: Run affected lint
run: pnpm turbo run lint --filter=...[origin/main]
- name: Run affected tests
run: pnpm turbo run test --filter=...[origin/main]
- name: Run affected build
run: pnpm turbo run build --filter=...[origin/main]# Split tasks across multiple CI agents
nx affected --target=build --parallel=3 --distributionInventory all repositories to migrate.
Document inter-repo dependencies.
Choose monorepo tooling (Nx, Turborepo, etc.).
Set up the monorepo skeleton.
Configure shared tooling (linting, TypeScript, testing).
# Import with full git history
git subtree add --prefix=packages/auth <auth-repo-url> main
# Or use a migration tool
npx nx import <repo-url> packages/my-packageFor each repository:
Import into the monorepo under packages/ or apps/.
Update import paths to use workspace references.
Replace published package dependencies with workspace:*.
Verify all tests pass.
Set up CI for the migrated package.
Consolidate shared dependencies.
Extract common configurations to root.
Set up affected detection and caching.
Migrate CI from per-repo to monorepo.
Archive old repositories (do not delete yet).
Monitor CI times. Optimize with caching and affected detection.
Extract shared libraries from duplicated code across packages.
Establish conventions for new packages.
Document the monorepo workflow for new developers.
Trying to migrate everything at once: Migrate one package at a time.
Losing git history: Use git subtree or dedicated migration tools.
Not updating CI: Monorepo CI must use affected detection from day one.
Ignoring dependency conflicts: Two repos may use incompatible versions of the same dependency. Resolve before or during migration.
No shared tooling setup: Without shared linting and testing config, the monorepo is just repos in a trench coat.
# Monorepo Manager Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement monorepo manager for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended monorepo manager approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When monorepo manager must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
505 lines · 1,881 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Monorepo Manager bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for