# Pathrule Pattern: Monorepo (pnpm + Turborepo) (1.0.0) # ::pathrule:package:monorepo-pnpm-turborepo ### [RULE] Every Turborepo task declares outputs, inputs, and env (path: /turbo.json) Turborepo only caches and replays a task correctly when its hash covers everything the task reads and produces. Configure each task so the hash is complete. - Set `outputs` to every artifact the task produces (for example `[".next/**", "!.next/cache/**"]` or `["dist/**"]`); a missing `outputs` means cache restores nothing. - Add build-time `env` entries for every variable that affects output, and set `envMode: "strict"` so undeclared variables cannot silently influence a build and invalidate the hash. - Use `dependsOn: ["^build"]` to build upstream packages first; mark `dev`/`watch` tasks `persistent: true` and `cache: false`. - Enabling Turborepo Remote Cache (`turbo login && turbo link`) shares hits across CI machines and branches; configure `remoteCache: { enabled: true }` in `turbo.json` and use the Vercel Remote Cache or a self-hosted Turborepo Cache Server. --- ### [RULE] Import workspace packages only through their exported public entry (path: /packages) Internal packages are consumed by their name and `exports` field, never by reaching across folder boundaries. This keeps the dependency graph honest and Turborepo Boundaries valid. - Import a workspace package as `@repo/ui` (resolved via its `package.json` `exports`), never as `../../packages/ui/src/...`. - Declare every workspace package you use in the consuming package's `package.json` as `"@repo/ui": "workspace:*"`; an undeclared import is an implicit dependency Turborepo cannot track. - Keep each package's public surface in its `exports` field and avoid deep subpath imports unless they are explicitly listed there. - Run `turbo boundaries` in CI to catch cross-package violations and undeclared dependencies before merge. --- ### [RULE] Pin the pnpm version in packageManager and CI (path: /) The `packageManager` field and the CI install action must agree on the exact pnpm version so the lockfile is interpreted identically everywhere. - Set `"packageManager": "pnpm@x.y.z"` (full semver) in the root `package.json`; this is enforced by Corepack when enabled. - Pin the same version in CI: for GitHub Actions, use `pnpm/action-setup` with an explicit `version` matching the `packageManager` field. - Commit `pnpm-lock.yaml`; never add it to `.gitignore`. - Run `pnpm install --frozen-lockfile` in CI so an out-of-date lockfile fails the build rather than silently resolving. --- ### [MEMORY] Pin shared dependency versions with pnpm catalogs (path: /pnpm-workspace.yaml) This repo uses pnpm workspace catalogs as the single source of truth for shared dependency versions, so every package stays on the same React, TypeScript, and tooling versions without manual syncing. - `pnpm-workspace.yaml` lists workspace globs under `packages:` (for example `apps/*` and `packages/*`) plus a `catalog:` block for the default catalog and optional named `catalogs:` for distinct version sets (for example `catalog:react19`). - Packages reference shared deps as `"react": "catalog:"` (default catalog) or `"react": "catalog:react19"` for a named one, instead of hard-coding a range in each package. - Bump a version in one place in the catalog and run `pnpm install`; pnpm rewrites the resolved lockfile entries across all packages automatically. - The content-addressable store hard-links shared deps, so a single `pnpm-lock.yaml` keeps installs deterministic and fast across all machines. --- ### [MEMORY] Share base tooling configs as internal workspace packages (path: /packages) Tooling configuration is published as internal config packages (for example `@repo/typescript-config`, `@repo/eslint-config`) rather than duplicated or pushed to the repo root. Each app and package extends the base it needs. - There is intentionally no root `tsconfig.json` for source compilation; each package has its own `tsconfig.json` that does `"extends": "@repo/typescript-config/base.json"`. - ESLint flat config and Tailwind/PostCSS presets are exported from config packages and imported so a rule change ships once and busts the cache in all dependents automatically. - List the config package as a `devDependency` with `workspace:*` so Turborepo tracks a config change as an input to all consumers. - Keep the root `package.json` for workspace-level scripts, the `turbo` binary dep, and `packageManager`; per-package concerns stay inside each package. --- ### [SKILL] monorepo-pnpm-turborepo-review (path: /) --- name: monorepo-pnpm-turborepo-review description: Review checklist for changes in a pnpm workspaces and Turborepo monorepo, covering task hashing and caching, package boundaries, catalog-pinned versions, shared configs, and pnpm version pinning. Use before merging any change that touches turbo.json, pnpm-workspace.yaml, package.json files, or cross-package imports. --- # Monorepo (pnpm + Turborepo) review ## Task pipeline and caching - [ ] Every new or changed `turbo.json` task sets `outputs` covering all produced artifacts and excludes cache dirs (e.g. `!.next/cache/**`). - [ ] Build-affecting env vars are declared in the task `env` or `globalEnv`; `envMode` is `strict`. - [ ] `dependsOn` uses `^build` for upstream packages; `dev`/`watch` tasks are `persistent: true` and `cache: false`. - [ ] Remote cache is configured if the team uses one (`turbo login` run, `remoteCache.enabled: true` in `turbo.json`). ## Package boundaries - [ ] New cross-package usage imports by package name (`@repo/*` via `exports`), never by relative or deep `src`/`dist` paths. - [ ] Each workspace package used is declared with `workspace:*` in the consuming package's `package.json`. - [ ] `turbo boundaries` and the build pass with no implicit dependencies. ## Dependencies and versions - [ ] Shared dependency versions use `catalog:` or a named `catalog:` instead of hard-coded ranges. - [ ] `pnpm-lock.yaml` is committed and reflects the current install; only one resolved version of each shared dep. - [ ] `packageManager` in the root `package.json` matches the pnpm version pinned in CI (`pnpm/action-setup` `version` field). - [ ] CI installs with `--frozen-lockfile`. ## Shared config - [ ] TypeScript, ESLint, and Tailwind extend the shared `@repo/*-config` packages rather than duplicating config. - [ ] Config package changes bust the cache in all downstream packages (listed as `devDependency workspace:*`).