Org Skills

Monorepo layout, shared packages and deployment

Supporting material for nodejs-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

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] 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.