Env vars em monorepo: o padrão que realmente escala em pnpm, Turborepo e Nx

Você tem três pacotes. Cada um precisa das próprias env vars. Alguém adicionou um quarto na sprint passada e o .env.example não é atualizado desde então. Uma pessoa nova entrou segunda e até agora não sobe o web app porque ninguém lembra quais keys vão onde — a resposta é sempre "pergunta pra Ana no Slack."

Até o fim desta página você tem um padrão concreto pra env vars em monorepo: um config na raiz do repo, escopo por pacote, overrides locais que não brigam com os do colega, e integração com task-runner pra pnpm workspaces, Turborepo e Nx. Você também vai saber onde cada pedaço do padrão ainda quebra — um padrão que finge resolver tudo é um padrão no qual você não pode confiar.

Por que .env-por-pacote para de funcionar em monorepo

Três modos de falha, na ordem em que pegam um time que está crescendo.

Os três padrões que os times tentam, e por que cada um quebra

Antes de nomear um padrão que funciona, uma passada rápida pelos que não funcionam. Quem já tentou um deles precisa entender por que falhou antes que um novo caminho faça sentido.

O formato da falha é sempre o mesmo: um padrão que aguenta 3 pacotes e 5 env vars desmorona em 8 pacotes e 30 env vars, e ninguém consegue apontar o momento em que parou de funcionar.

Como é a resposta certa (independente de ferramenta)

Antes de nomear um produto, aqui está o formato de uma solução que escala. Se você não tem algo assim no seu monorepo, ele vai parar de funcionar pelos mesmos motivos dos padrões acima — não importa se você constrói na mão ou adota uma ferramenta.

Uma resposta que te dá três desses quatro deixa um vetor de drift em pé. Você quer os quatro.

Como o Envshed implementa esse padrão

O Envshed é um gerenciador de secrets hospedado com uma CLI que lê um único arquivo de config na raiz do repo. O config mapeia workspaces pra projects na sua organização Envshed. envshed pull percorre o config, busca as keys que cada workspace declarou e escreve em disco onde o seu código já espera encontrar.

Este é o schema real do .envshed.json (pacote → { 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 aponta pro próprio project Envshed. Um envshed pull na raiz busca de todos os workspaces em paralelo. envshed pull --workspace apps/api limita o pull a um pacote só — útil em jobs de CI que tocam num serviço só.

O campo file sobrescreve o caminho de saída padrão (./.env relativo ao workspace). Use .env.local nos workspaces onde o Next.js ou o Vite espera esse arquivo.

Os valores dos secrets ficam criptografados em repouso com AES-256-GCM no lado do Envshed; envshed pull descriptografa em trânsito e escreve nos caminhos acima. Nada é logado no servidor, e nada do seu config sai do repo.

Passo a passo: pnpm workspaces

O pnpm-workspace.yaml do pnpm declara os globs dos pacotes. envshed init lê esse arquivo direto quando você roda na raiz do repo.

Passo 1 — Detecte e escolha os pacotes.

envshed init lê o pnpm-workspace.yaml e mostra todo pacote que encontra nos globs configurados. Escolha os que você quer rastrear — por padrão, todos.

Passo 2 — Mapeie cada pacote num project Envshed.

Pra cada pacote escolhido, selecione ou crie um project Envshed e um ambiente. A CLI escreve o mapeamento no .envshed.json na raiz do repo.

Passo 3 — Commite o config.

O .envshed.json não tem valores de secret — só slugs e caminhos de arquivo — então é seguro commitar. Esse commit também vira o seu doc de onboarding: a pessoa nova clona o repo, roda envshed pull e o monorepo inteiro sobe.

A partir daí, puxar secrets é um comando só:

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

Pluga no seu script dev pra todo start local pegar os valores mais recentes:

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

O pull leva algumas centenas de milissegundos a frio, então o pnpm dev de ninguém fica mais lento. Referência da CLI: envshed init, envshed workspace, envshed pull.

Passo a passo: Turborepo

O superpoder do Turborepo é o cache de tarefas. O ponto cego — aquele que manda env vars quebradas pra prod — é que ele só faz hash das env vars declaradas no turbo.json. Este é o arranjo que faz Envshed e Turbo concordarem.

Passo 1 — Torne o pull uma dependência da tarefa.

Declare uma tarefa envshed:pull e puxe via dependsOn. Defina cache: false tanto no pull quanto em qualquer tarefa persistent de longa duração — o pull precisa rodar toda vez pra pegar valores rotacionados, e tarefas persistent não são cacheáveis mesmo.

Passo 2 — Declare toda env var no env do Turbo.

Qualquer coisa que o seu build lê via process.env e não está listada aqui é invisível pro hash de cache do Turbo. Env vars não declaradas são o motivo #1 de "funciona na minha máquina, cacheado-quebrado na CI". Mantenha essa lista honesta.

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

Passo 3 — Pluga na CI com um service token.

Na CI, emita um service token Envshed com escopo por ambiente, defina como secret da CI e chame envshed pull no início do job. O token é o único valor específico do Envshed que o seu config de CI precisa — todo o resto rotaciona no Envshed.

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

Passo a passo: Nx

O Nx modela todo app e biblioteca como um project separado, cada um com o próprio project.json. O mapa workspaces do .envshed.json alinha um a um: uma entrada de workspace Envshed por project Nx.

Passo 1 — Deixe cada project ler o próprio .env.

O Nx pega automaticamente apps/<nome>/.env quando executa um target no cwd desse project, então basta envshed pull escrever nesse caminho.

Passo 2 — Torne o pull uma dependência de tarefa do Nx.

Adicione um target run-commands local por project e encadeie com dependsOn nos targets que precisam de 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"
    }
  }
}

Passo 3 — Declare env vars em namedInputs.

O Nx só faz hash das env vars que você declara — mesma regra do Turbo. Use namedInputs pra esse conjunto ser reutilizável entre targets:

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

O que não fingimos resolver

Porque você vai notar se não falarmos disso.

Esses limites seguram o resto. Um gerenciador de secrets que diz resolver tudo é ou um proxy que você tem que operar ou um lock-in do qual você não consegue sair. O Envshed não é nenhum dos dois.

FAQ

Veja o padrão rodando

Em vez de copiar snippets desta página, clone o monorepo de demo. São três pacotes — uma API Fastify, um web app Next.js 15 e uma biblioteca de auth compartilhada — montados com pnpm-workspace.yaml, turbo.json e um .envshed.json usando o schema real deste guia. Do git clone até um servidor de dev rodando em menos de cinco minutos.

Leitura relacionada