# Monorepo patterns

Loaded on demand from `../SKILL.md`.

## Task graph

The build tool needs to know, for each task, what it depends on, what inputs
change its result, and what outputs it produces. With that, it can order work,
run independent tasks in parallel and skip tasks whose inputs did not change.

Turborepo:

```json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "test/**"],
      "outputs": ["coverage/**"]
    },
    "lint": {},
    "dev": { "cache": false, "persistent": true }
  }
}
```

`^build` means "build my dependencies first". Nx expresses the same with
`targetDefaults` and `namedInputs` in `nx.json`, and can infer targets from
tool config files.

Rules that keep caching correct:

- Declare every input that changes output, including env vars
  (`env` in Turborepo, `{env.X}` inputs in Nx). An undeclared input gives stale
  cache hits.
- Declare outputs precisely; a missing output is not restored on a hit.
- Tasks must be deterministic: no timestamps or absolute paths in artifacts.

## Versioning and release with Changesets

```bash
pnpm changeset          # author picks packages and bump type, writes a note
pnpm changeset version  # applies bumps, updates changelogs and dependents
pnpm changeset publish  # publishes what changed, tags releases
```

- Each PR that changes a published package includes a changeset file; a CI
  check fails when one is missing.
- The Changesets GitHub action opens a "Version Packages" PR; merging it
  publishes.
- `fixed` groups keep packages on one shared version; `linked` bumps them
  together only when released together.
- Apps are not versioned by Changesets; they deploy by commit.

## Migrating repos in

1. Import each repo with history into its target folder (`git subtree add` or
   `git filter-repo --to-subdirectory-filter`), one at a time.
2. Align toolchain versions (Node, TypeScript, lint config) before merging
   dependency trees.
3. Replace published-version dependencies between the imported projects with
   `workspace:` links.
4. Add the task graph and affected CI before the third project arrives, not
   after CI times double.
