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 → Require pnpm and turborepo.
| Item |
Required |
When |
How |
| pnpm |
required |
Always |
npx skills add antfu/skills --skill pnpm |
| 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 |
| Cross-package import |
Library or app importing another workspace package |
managing-imports.md |
Change exports / scoped name |
Editing a package's public surface or @scope/ name |
managing-imports.md |
| In-package JIT alias |
A library consumed as TypeScript source aliases its own internals |
managing-imports.md |
| Package runner |
Adding or renaming a package script, or wiring root <dir>:<script> |
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.
Reference index
Contract
monorepo-contract.md — toolchain, folder roles, scoped names, exports, package runners, JIT vs compiled.
1---2name: managing-monorepo3description: 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`.4---56# Managing Monorepo78## Overview910Workspace contract: folder roles, cross-package imports, package runners, and the Turbo task graph.1112### Tech stack1314| Layer | Choice |15| --- | --- |16| Language | TypeScript |17| Package manager | pnpm (workspaces) |18| Task runner | Turborepo |1920## Dependencies2122Resolve 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**.2324| Item | Required | When | How |25| --- | --- | --- | --- |26| [pnpm](https://github.com/antfu/skills/tree/main/skills/pnpm) | required | Always | `npx skills add antfu/skills --skill pnpm` |27| [turborepo](https://github.com/antfu/skills/tree/main/skills/turborepo) | required | Always | `npx skills add antfu/skills --skill turborepo` |2829Install both: `npx skills add antfu/skills --skill pnpm --skill turborepo`3031## Agent workflow3233Follow 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.3435### Entry points3637Use the first matching row; combine when the task spans types.3839| Entry | When | Go to |40| --- | --- | --- |41| 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) |42| Cross-package import | Library or app importing another workspace package | [managing-imports.md](./references/managing-imports.md) |43| Change `exports` / scoped name | Editing a package's public surface or `@scope/` name | [managing-imports.md](./references/managing-imports.md) |44| In-package JIT alias | A library consumed as TypeScript source aliases its own internals | [managing-imports.md](./references/managing-imports.md) |45| Package runner | Adding or renaming a package script, or wiring root `<dir>:<script>` | [managing-scripts.md](./references/managing-scripts.md) |46| Lookup | Known doc name or single reference | **Reference index** |4748### Task types4950Match every row that applies. Open every local link in **Docs** before coding.5152| Task type | Docs |53| --- | --- |54| New workspace | [monorepo-contract.md](./references/monorepo-contract.md), [managing-workspace.md](./references/managing-workspace.md), [managing-scripts.md](./references/managing-scripts.md) |55| 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) |5657## Reference index5859### Contract6061[monorepo-contract.md](./references/monorepo-contract.md) — toolchain, folder roles, scoped names, `exports`, package runners, JIT vs compiled.6263| Doc | When to use |64| --- | --- |65| [monorepo-contract.md](./references/monorepo-contract.md) | Toolchain, roles, names, `exports`, package runners, resolve root |66| [managing-workspace.md](./references/managing-workspace.md) | Layout, globs, add package, initialize workspace, root `.gitignore` |67| [managing-imports.md](./references/managing-imports.md) | Cross-package and in-package import rules |68| [managing-scripts.md](./references/managing-scripts.md) | Root `<dir>:<script>` runners; Turbo graph rules |
cedmandocdoc