# Monorepo layout, shared packages and deployment

Verified 2026-09 against <https://pnpm.io/workspaces>, <https://turborepo.com/docs>,
<https://nx.dev/getting-started/intro> and
<https://www.typescriptlang.org/docs/handbook/project-references.html>.

## 1. Layout

```
pnpm-workspace.yaml
turbo.json                  (or nx.json)
apps/
  orders-api/               a deployable service
  billing-worker/
packages/
  contracts/                schemas, event types, generated clients
  platform/                 logger, config helpers, telemetry bootstrap
  tsconfig/                 base tsconfig files
  eslint-config/
```

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

Internal dependencies use the workspace protocol so they are never fetched from a registry:

```json
{ "dependencies": { "@acme/contracts": "workspace:*" } }
```

The distinction that keeps a monorepo healthy: `apps/*` are deployables and depend on packages;
`packages/*` never depend on apps and never on each other in a cycle.

## 2. What may be shared

| Share | Why it is safe |
|---|---|
| **Contracts** — request/response schemas, event types, generated API clients | They *are* the coupling, made explicit and versioned |
| **Platform utilities** — logger factory, config parsing helpers, telemetry bootstrap | No domain knowledge, changes rarely |
| **Tooling config** — tsconfig bases, ESLint config, test setup | Consistency with no runtime coupling |

| Do not share | Why |
|---|---|
| **Domain entities** | Two services then change together; you have one service with a network in the middle |
| **A `utils` grab-bag** | Everything depends on it, everyone edits it, nothing can change |
| **Database clients or schemas across services** | Data ownership is the boundary; sharing the client erases it |

If two services genuinely need the same rule, ask which one *owns* it. The other calls it or consumes
its events.

## 3. TypeScript project references

Project references give incremental builds and make the dependency graph a compile-time fact:

```jsonc
// apps/orders-api/tsconfig.json
{
  "extends": "@acme/tsconfig/node.json",
  "compilerOptions": { "outDir": "dist", "rootDir": "src", "composite": true },
  "references": [{ "path": "../../packages/contracts" }]
}
```

Referenced packages need `"composite": true` and must emit declarations. `tsc --build` then rebuilds
only what changed. A package that is referenced but not listed fails the build, which is the point:
an accidental import cannot slip through as an untyped `any`.

## 4. Turborepo or Nx

| | Turborepo | Nx |
|---|---|---|
| Model | Task runner and cache over your existing scripts | Task runner plus generators, graph and boundary enforcement |
| Config | `turbo.json` with task inputs and outputs | `nx.json` plus per-project configuration |
| Learn cost | An afternoon | A week, and a convention for the whole team |
| Pick when | You want caching and affected builds, nothing more | You want enforced boundaries, generators and a managed graph |

```jsonc
// turbo.json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "test": { "dependsOn": ["build"] },
    "typecheck": { "dependsOn": ["^build"] },
    "lint": {}
  }
}
```

`"dependsOn": ["^build"]` means "build my dependencies first". Getting `outputs` right is what makes
the cache correct — a task that writes files not listed there will appear to succeed from cache while
producing nothing.

## 5. Building one service's image

Copying the whole monorepo into a Docker build sends every app's source to the daemon and busts the
layer cache on any change. Prune first.

```dockerfile
# Turborepo
FROM node:24-slim AS prune
WORKDIR /app
COPY . .
RUN npx turbo prune @acme/orders-api --docker

FROM node:24-slim AS build
WORKDIR /app
COPY --from=prune /app/out/json/ .
RUN npm i -g pnpm && pnpm install --frozen-lockfile
COPY --from=prune /app/out/full/ .
RUN pnpm turbo run build --filter=@acme/orders-api

FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /app .
USER node
CMD ["node", "apps/orders-api/dist/server.js"]
```

`turbo prune --docker` emits `out/json` (just the manifests) and `out/full` (the sources). Installing
from the manifests alone in its own layer means the dependency layer is cached until a manifest
changes. Without pnpm, `pnpm deploy --filter` produces a similar self-contained folder.

## 6. CI

- Build and test only what changed: `turbo run test --filter=...[origin/main]` or
  `nx affected -t test`. On a repository with twenty apps this is the difference between a
  four-minute and a forty-minute pipeline.
- Cache remotely so CI and developers share hits. Cache keys must include the lockfile and the
  tooling versions, or a dependency bump will serve a stale build.
- Keep one lockfile at the root, committed, and install with `--frozen-lockfile` everywhere.
- Publish internal packages only if something outside the repository consumes them. Inside the
  workspace, `workspace:*` is simpler and always consistent — a version number between two packages
  that always deploy together is bookkeeping with no reader.
