# Managing Monorepo

> Defines the workspace contract for a TypeScript monorepo with pnpm and Turborepo — folder roles (`apps/` vs `packages/`), cross-package imports (`exports`, `workspace:*`), package runners (`<dir>:<script>`, e.g. `pnpm web:dev`), and root `.gitignore`. Use when adding a package, choosing apps vs packages, wiring an import, adding a package script or root runner, or initializing `.gitignore`.

- Skill: `cedmandocdoc/managing-monorepo` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add cedmandocdoc/managing-monorepo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cedmandocdoc/managing-monorepo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: cedmandocdoc (https://skillmd.com/u/cedmandocdoc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cedmandocdoc/managing-monorepo

---


# Managing Monorepo

## Overview

Workspace contract: folder roles, cross-package imports, package runners, and the Turbo task graph.

### Tech stack

| Layer | Choice |
| --- | --- |
| Language | TypeScript |
| Package manager | pnpm (workspaces) |
| Task runner | Turborepo |

## Dependencies

Resolve every **required** row before recipes that need it. Skill discovery and missing-skill stop text: [monorepo-contract.md](./references/monorepo-contract.md) → **Require pnpm and turborepo**.

| Item | Required | When | How |
| --- | --- | --- | --- |
| [pnpm](https://github.com/antfu/skills/tree/main/skills/pnpm) | required | Always | `npx skills add antfu/skills --skill pnpm` |
| [turborepo](https://github.com/antfu/skills/tree/main/skills/turborepo) | required | Always | `npx skills add antfu/skills --skill turborepo` |

Install both: `npx skills add antfu/skills --skill pnpm --skill turborepo`

## Agent workflow

Follow this skill for TypeScript pnpm + Turborepo workspaces. Works wherever the agent can read `package.json`. Match **Entry points**; for a new package or workspace open every **Task types** row that applies.

### Entry points

Use the first matching row; combine when the task spans types.

| Entry | When | Go to |
| --- | --- | --- |
| Workspace / new package | Init workspace, choose `apps/` vs `packages/`, add or move a package, init or fix `.gitignore` | [managing-workspace.md](./references/managing-workspace.md) |
| Cross-package import | Library or app importing another workspace package | [managing-imports.md](./references/managing-imports.md) |
| Change `exports` / scoped name | Editing a package's public surface or `@scope/` name | [managing-imports.md](./references/managing-imports.md) |
| In-package JIT alias | A library consumed as TypeScript source aliases its own internals | [managing-imports.md](./references/managing-imports.md) |
| Package runner | Adding or renaming a package script, or wiring root `<dir>:<script>` | [managing-scripts.md](./references/managing-scripts.md) |
| Lookup | Known doc name or single reference | **Reference index** |

### Task types

Match every row that applies. Open every local link in **Docs** before coding.

| Task type | Docs |
| --- | --- |
| New workspace | [monorepo-contract.md](./references/monorepo-contract.md), [managing-workspace.md](./references/managing-workspace.md), [managing-scripts.md](./references/managing-scripts.md) |
| New package | [monorepo-contract.md](./references/monorepo-contract.md), [managing-workspace.md](./references/managing-workspace.md), [managing-imports.md](./references/managing-imports.md), [managing-scripts.md](./references/managing-scripts.md) |

## Reference index

### Contract

[monorepo-contract.md](./references/monorepo-contract.md) — toolchain, folder roles, scoped names, `exports`, package runners, JIT vs compiled.

| Doc | When to use |
| --- | --- |
| [monorepo-contract.md](./references/monorepo-contract.md) | Toolchain, roles, names, `exports`, package runners, resolve root |
| [managing-workspace.md](./references/managing-workspace.md) | Layout, globs, add package, initialize workspace, root `.gitignore` |
| [managing-imports.md](./references/managing-imports.md) | Cross-package and in-package import rules |
| [managing-scripts.md](./references/managing-scripts.md) | Root `<dir>:<script>` runners; Turbo graph rules |