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/
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'
Internal dependencies use the workspace protocol so they are never fetched from a registry:
{ "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:
// 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 |
// 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.
# 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]ornx 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-lockfileeverywhere. - 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.