# Monorepo Navigator

> Monorepo Navigator

- Skill: `neekware/monorepo-navigator` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add neekware/monorepo-navigator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neekware/monorepo-navigator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: neekware (https://skillmd.com/u/neekware)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/neekware/monorepo-navigator

---


> **Note:** Bundled scripts ship as Markdown reference (`.md`) — copy the code out of the `.md` file to run it.

# Monorepo Navigator

**Tier:** POWERFUL  
**Category:** Engineering  
**Domain:** Monorepo Architecture / Build Systems

---

## Overview

Navigate, manage, and optimize monorepos. Covers Turborepo, Nx, pnpm workspaces, and Lerna. Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo. Includes Claude Code configuration for workspace-aware development.

---

## Core Capabilities

- **Cross-package impact analysis** — determine which apps break when a shared package changes
- **Selective commands** — run tests/builds only for affected packages (not everything)
- **Dependency graph** — visualize package relationships as Mermaid diagrams
- **Build optimization** — remote caching, incremental builds, parallel execution
- **Migration** — step-by-step multi-repo → monorepo with zero history loss
- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows
- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions

---

## When to Use

Use when:

- Multiple packages/apps share code (UI components, utils, types, API clients)
- Build times are slow because everything rebuilds when anything changes
- Migrating from multiple repos to a single repo
- Need to publish packages to npm with coordinated versioning
- Teams work across multiple packages and need unified tooling

Skip when:

- Single-app project with no shared packages
- Team/project boundaries are completely isolated (polyrepo is fine)
- Shared code is minimal and copy-paste overhead is acceptable

---

## Tool Selection

| Tool                | Best For                                 | Key Feature                                       |
| ------------------- | ---------------------------------------- | ------------------------------------------------- |
| **Turborepo**       | JS/TS monorepos, simple pipeline config  | Best-in-class remote caching, minimal config      |
| **Nx**              | Large enterprises, plugin ecosystem      | Project graph, code generation, affected commands |
| **pnpm workspaces** | Workspace protocol, disk efficiency      | `workspace:*` for local package refs              |
| **Lerna**           | npm publishing, versioning               | Batch publishing, conventional commits            |
| **Changesets**      | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels        |

Most modern setups: **pnpm workspaces + Turborepo + Changesets**

---

## Turborepo

→ See references/monorepo-tooling-reference.md for details

## Workspace Analyzer

```bash
python3 scripts/monorepo_analyzer.py /path/to/monorepo
python3 scripts/monorepo_analyzer.py /path/to/monorepo --json
```

Also see `references/monorepo-patterns.md` for common architecture and CI patterns.

## Common Pitfalls

| Pitfall                                                     | Fix                                                                                       |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Running `turbo run build` without `--filter` on every PR    | Always use `--filter=...[origin/main]` in CI                                              |
| `workspace:*` refs cause publish failures                   | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |
| All packages rebuild when unrelated file changes            | Tune `inputs` in turbo.json to exclude docs, config files from cache keys                 |
| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir`     |
| git history lost during migration                           | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |
| Remote cache not working in CI                              | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize`      |
| CLAUDE.md too generic — Claude modifies wrong package       | Add explicit "When working on X, only touch files in apps/X" rules per package CLAUDE.md  |

---

## Best Practices

1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules
2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands
3. **Always scope commands with --filter** — running everything on every change defeats the purpose
4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI
5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo
6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js
7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius
8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check