Env vars en monorepo: el patrón que de verdad escala en pnpm, Turborepo y Nx

Tienes tres paquetes. Cada uno necesita sus propias env vars. Alguien añadió un cuarto el sprint pasado y el .env.example no se actualiza desde entonces. Una persona nueva entró el lunes y todavía no puede levantar el web app porque nadie recuerda qué keys van dónde — la respuesta siempre es "pregúntale a Ana por Slack."

Al final de esta página tendrás un patrón concreto para env vars en un monorepo: un config en la raíz del repo, alcance por paquete, overrides locales que no pelean con los de tu compañero, e integración con task-runner para pnpm workspaces, Turborepo y Nx. También vas a saber dónde sigue rompiéndose cada pieza del patrón — un patrón que pretende resolverlo todo es un patrón del que no puedes fiarte.

Por qué .env-por-paquete deja de funcionar en un monorepo

Tres modos de falla, en el orden en que le pegan a un equipo que crece.

Los tres patrones a los que recurren los equipos, y por qué cada uno se rompe

Antes de nombrar un patrón que funciona, un repaso rápido por los que no. Quien ya probó uno de ellos necesita entender por qué falló antes de que un camino nuevo le cuaje.

La forma de la falla siempre es la misma: un patrón que aguanta 3 paquetes y 5 env vars se desmorona con 8 paquetes y 30 env vars, y nadie puede señalar el momento en que dejó de funcionar.

Cómo se ve la respuesta correcta (independiente de herramienta)

Antes de nombrar un producto, aquí está la forma de una solución que escala. Si no tienes algo así en tu monorepo, va a dejar de funcionar por los mismos motivos que los patrones de arriba — da igual si lo construyes tú o si adoptas una herramienta.

Una respuesta que te da tres de estos cuatro deja un vector de drift en pie. Quieres los cuatro.

Cómo Envshed implementa ese patrón

Envshed es un gestor de secrets hospedado con un CLI que lee un único archivo de config en la raíz de tu repo. El config mapea workspaces a projects en tu organización Envshed. envshed pull recorre el config, trae las keys que cada workspace declaró y las escribe en disco donde tu código ya espera encontrarlas.

Este es el schema real de .envshed.json (paquete → { 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" }
  }
}

Cada entrada de workspace apunta a su propio project Envshed. Un envshed pull en la raíz va a cada workspace en paralelo. envshed pull --workspace apps/api acota el pull a un paquete — útil en jobs de CI que tocan un solo servicio.

El campo file sobrescribe la ruta de salida por defecto (./.env relativo al workspace). Usa .env.local en los workspaces donde Next.js o Vite esperan ese archivo.

Los valores de los secrets se almacenan cifrados en reposo con AES-256-GCM del lado de Envshed; envshed pull los descifra en tránsito y los escribe en las rutas de arriba. Nada se loguea del lado del servidor, y nada de tu config sale del repo.

Walkthrough: pnpm workspaces

El pnpm-workspace.yaml de pnpm declara los globs de paquetes. envshed init lee ese archivo directamente cuando lo ejecutas en la raíz del repo.

Paso 1 — Detecta y elige los paquetes.

envshed init lee pnpm-workspace.yaml y muestra cada paquete que encuentra bajo los globs configurados. Elige los que quieras trackear — por defecto, todos.

Paso 2 — Mapea cada paquete a un project Envshed.

Para cada paquete elegido, elige o crea un project Envshed y un ambiente. El CLI escribe el mapeo en .envshed.json en la raíz del repo.

Paso 3 — Commitea el config.

.envshed.json no tiene valores de secret — solo slugs y rutas de archivo — así que es seguro commitearlo. Ese commit también es tu doc de onboarding: una persona nueva clona el repo, corre envshed pull, y todo el monorepo levanta.

De ahí en adelante, traer secrets es un comando:

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

Conéctalo a tu script dev para que cada arranque local tome los valores más recientes:

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

El pull tarda unos cientos de milisegundos en frío, así que el pnpm dev de nadie se siente más lento. Referencia del CLI: envshed init, envshed workspace, envshed pull.

Walkthrough: Turborepo

El superpoder de Turborepo es el cache de tareas. Su punto ciego — el que manda env vars rotas a prod — es que solo hashea las env vars declaradas en turbo.json. Este es el cableado que hace que Envshed y Turbo se pongan de acuerdo.

Paso 1 — Haz que el pull sea dependencia de la tarea.

Declara una tarea envshed:pull y arrástrala vía dependsOn. Pon cache: false tanto en el pull como en cualquier tarea persistent de larga duración — el pull tiene que correr cada vez para tomar valores rotados, y las tareas persistent no son cacheables igualmente.

Paso 2 — Declara cada env var en el env de Turbo.

Cualquier cosa que tu build lea vía process.env y no esté listada aquí es invisible para el hash de cache de Turbo. Las env vars no declaradas son la causa #1 de "funciona en mi máquina, cacheado-roto en CI". Mantén honesta esta lista.

{
  "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/**"]
    }
  }
}

Paso 3 — Conéctalo a CI con un service token.

En CI, emite un service token Envshed con alcance por ambiente, fíjalo como secret de CI y llama a envshed pull al inicio del job. El token es el único valor específico de Envshed que tu config de CI necesita — todo lo demás rota en Envshed.

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

Walkthrough: Nx

Nx modela cada app y librería como un project aparte con su propio project.json. El mapa workspaces de .envshed.json calza uno a uno: una entrada de workspace Envshed por project Nx.

Paso 1 — Deja que cada project lea su propio .env.

Nx toma automáticamente apps/<nombre>/.env cuando ejecuta un target en el cwd de ese project, así que basta con que envshed pull escriba en esa ruta.

Paso 2 — Haz el pull dependencia de tarea en Nx.

Agrega un target run-commands local por project y encadénalo con dependsOn en los targets que necesitan 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"
    }
  }
}

Paso 3 — Declara env vars en namedInputs.

Nx solo hashea las env vars que declares — misma regla que Turbo. Usa namedInputs para que ese conjunto sea reutilizable entre targets:

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

Lo que no pretendemos resolver

Porque lo vas a notar si no lo decimos.

Estos límites sostienen el resto. Un gestor de secrets que dice resolverlo todo es, o bien un proxy que tienes que operar, o bien un lock-in del que no puedes salir. Envshed no es ninguno.

FAQ

Mira el patrón corriendo

En vez de copiar snippets de esta página, clona el monorepo de demo. Son tres paquetes — una API Fastify, un web app Next.js 15 y una librería de auth compartida — cableados con pnpm-workspace.yaml, turbo.json y un .envshed.json usando el schema real de esta guía. De git clone a un servidor de dev corriendo en menos de cinco minutos.

Lectura relacionada