Monorepo env vars: the pattern that actually scales across pnpm, Turborepo, and Nx

You have three packages. Each one needs its own env vars. Someone added a fourth last sprint and the .env.example hasn't been updated since. A new hire joined Monday and still can't boot the web app because nobody remembers which keys belong where — the answer is always "ask Ana on Slack."

By the end of this page you have a concrete pattern for env vars in a monorepo: one config at the repo root, per-package scoping, local overrides that don't fight your teammates', and task-runner integration for pnpm workspaces, Turborepo, and Nx. You'll also know where each piece of the pattern still breaks — a pattern that pretends to solve everything is a pattern you can't trust.

Why .env-per-package stops working in a monorepo

Three failure modes, in the order they hit a growing team.

The three patterns teams reach for, and why each one breaks

Before we name a pattern that works, a quick tour of the ones that don't. A reader who's already tried one of these needs to understand why it failed before a new one will land.

The shape of the failure is always the same: a pattern that holds for 3 packages and 5 env vars falls over at 8 packages and 30 env vars, and nobody can point to the moment it stopped working.

What the right answer looks like (tool-agnostic)

Before we name a product, here's the shape of a solution that scales. If you don't have something like this in your monorepo, it will stop working for the same reasons the patterns above did — whether you build it yourself or adopt a tool.

An answer that gives you three of these four leaves one drift vector in place. You want all four.

How Envshed implements that pattern

Envshed is a hosted secrets manager with a CLI that reads a single config file at your repo root. The config maps workspaces to projects in your Envshed organization. envshed pull walks the config, fetches the keys each workspace declared, and writes them to disk where your code already expects to find them.

Here's the real .envshed.json schema (package → { project, defaultEnv?, file?, org? }):

{
  "org": "acme",
  "project": "platform",
  "defaultEnv": "development",
  "workspaces": {
    "apps/api":      { "project": "platform-api" },
    "apps/web":      { "project": "platform-web", "defaultEnv": "development" },
    "packages/auth": { "project": "platform-auth", "file": ".env.local" }
  }
}

Each workspace entry points to its own Envshed project. One envshed pull at the root hits every workspace in parallel. envshed pull --workspace apps/api scopes the pull to a single package — useful in CI jobs that only touch one service.

The file field overrides the default output path (./.env relative to the workspace). Use .env.local for the workspaces where Next.js or Vite expects it.

Secret values are encrypted at rest with AES-256-GCM on the Envshed side; envshed pull decrypts them in-flight and writes them to the paths above. Nothing gets logged server-side, and nothing about your config leaves the repo.

Walkthrough: pnpm workspaces

pnpm's pnpm-workspace.yaml declares package globs. envshed init reads that file directly when you run it at the repo root.

Step 1 — Detect and pick packages.

envshed init reads pnpm-workspace.yaml and shows every package it finds under the configured globs. Pick the ones you want to track — the default is all of them.

Step 2 — Map each package to an Envshed project.

For each selected package, pick or create an Envshed project and an environment. The CLI writes the mapping into .envshed.json at the repo root.

Step 3 — Commit the config.

.envshed.json has no secret values — only slugs and file paths — so it's safe to commit. That commit is also your onboarding doc: a new hire clones the repo, runs envshed pull, and the full monorepo boots.

From there, pulling secrets is one command:

envshed pull                       # pulls every workspace in parallel
envshed pull --workspace apps/api  # scopes the pull to one package
envshed pull --env staging         # same config, staging values

Wire it into your dev script so every local start picks up the latest values:

{
  "scripts": {
    "dev": "envshed pull && turbo run dev"
  }
}

The pull takes a few hundred milliseconds cold, so nobody's pnpm dev feels slower. CLI reference: envshed init, envshed workspace, envshed pull.

Walkthrough: Turborepo

Turborepo's superpower is task caching. Its blind spot — the one that ships broken env vars to prod — is that it only hashes the env vars you declare in turbo.json. Here's the wiring that makes Envshed and Turbo agree with each other.

Step 1 — Make the pull a task dependency.

Declare an envshed:pull task and pull it in via dependsOn. Set cache: false on both the pull and any long-running persistent task — the pull has to run every time to pick up rotated values, and persistent tasks are never cacheable anyway.

Step 2 — Declare every env var in Turbo's env.

Anything your build reads via process.env that isn't listed here is invisible to Turbo's cache hashing. Undeclared env vars are the #1 cause of "works on my machine, cached-broken on CI." Keep this list honest.

{
  "tasks": {
    "envshed:pull": {
      "cache": false
    },
    "dev": {
      "dependsOn": ["envshed:pull"],
      "persistent": true,
      "cache": false
    },
    "build": {
      "dependsOn": ["envshed:pull", "^build"],
      "env": ["DATABASE_URL", "STRIPE_SECRET_KEY", "NEXTAUTH_SECRET"],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

Step 3 — Wire it into CI with a service token.

In CI, issue a scoped Envshed service token per environment, set it as a CI secret, and call envshed pull at the start of the job. The token is the only Envshed-specific value your CI config needs — everything else rotates in Envshed.

- run: envshed pull
  env:
    ENVSHED_TOKEN: ${{ secrets.ENVSHED_CI_TOKEN }}

Walkthrough: Nx

Nx models every app and library as a separate project with its own project.json. The .envshed.json workspaces map lines up one-to-one: one Envshed workspace entry per Nx project.

Step 1 — Let each project read its own .env.

Nx automatically picks up apps/<name>/.env when executing a target in that project's cwd, so envshed pull writing to that path is all you need.

Step 2 — Make the pull an Nx task dependency.

Add a local run-commands target per project and chain it with dependsOn on the targets that need secrets:

{
  "name": "api",
  "targets": {
    "envshed": {
      "executor": "nx:run-commands",
      "options": {
        "command": "envshed pull --workspace apps/api",
        "cwd": "{workspaceRoot}"
      }
    },
    "serve": {
      "dependsOn": ["envshed"],
      "executor": "@nx/node:node"
    }
  }
}

Step 3 — Declare env vars in namedInputs.

Nx only hashes env vars you declare — same rule as Turbo. Use namedInputs so the env set is reusable across targets:

{
  "namedInputs": {
    "runtime": [
      { "env": "DATABASE_URL" },
      { "env": "REDIS_URL" }
    ]
  },
  "targetDefaults": {
    "build": { "inputs": ["default", "runtime"] }
  }
}

The parts we don't pretend to solve

Because you'll notice if we don't say it.

These limits are load-bearing. A secrets manager that claims to solve everything is either a proxy you have to operate or a lock-in you can't leave. Envshed is neither.

FAQ

See the pattern running

Rather than copy snippets from this page, clone the demo monorepo. It's three packages — a Fastify API, a Next.js 15 web app, and a shared auth library — wired up with pnpm-workspace.yaml, turbo.json, and an .envshed.json using the real schema from this guide. From git clone to a running dev server in under five minutes.

Related reading