Env vars no monorepo, sem o .env se espalhando.

Cada pacote quer os próprios secrets. Cada dev quer um único comando. Um .envshed.json na raiz, cada workspace puxa as chaves que precisa, e os overrides por usuário ficam locais.

O monorepo é o momento em que o dotenv para de escalar. O pacote A precisa de uma chave Stripe. O B precisa de uma URL de Postgres. O C precisa das duas. A próxima pessoa do time copia três arquivos do Slack, esquece um, e a aplicação quebra no boot com um undefined cifrado. O Envshed foi feito pra manter a estrutura que você já tem — e tirar os secrets do lugar de elo frágil.

Onde secrets em monorepo dão errado

Três pacotes, três .env, uma pessoa mantendo tudo alinhado

Uma engenheira vira a dependência ambulante. Ela tira férias e o setup do dev novo quebra de um jeito que ninguém consegue reproduzir.

Pacote novo entra na terça, as chaves dele somem na sexta

Ninguém lembra quais env vars pertencem ao pacote que entrou sprint passada. O .env.example vai dessincronizando uma linha por vez.

O Turbo cacheia uma task sem a env var

O cache trata a chave faltante como build válido. O bug sobrevive uma semana porque o CI que deveria quebrar veio do cache.

Um config que entende o formato do seu workspace

O Envshed trata o monorepo como estrutura de primeira classe. Um único arquivo na raiz declara o ambiente de cada pacote. envshed pull percorre o config, busca só as chaves que cada workspace declarou e escreve onde o workspace espera. pnpm workspaces, Turborepo, Nx, Lerna — se a ferramenta lê process.env, o Envshed entrega os valores.

Declara uma vez, puxa por workspace

Um arquivo de configuração. Cada pacote puxa o que precisa.

// .envshed.json na raiz do repo
{
  "org": "acme",
  "project": "platform",
  "defaultEnv": "development",
  "workspaces": {
    "apps/api": ["DATABASE_URL", "REDIS_URL"],
    "apps/web": ["NEXT_PUBLIC_API_URL"],
    "packages/auth": ["JWT_SECRET"]
  }
}

O que isso substitui

Pull escopado por workspace

envshed pull --workspace apps/api só escreve as chaves que o app API declarou. Pacote de frontend nunca vê o Stripe secret.

Chave faltante detectada antes do boot

O Envshed falha em voz alta quando um workspace declara uma chave que não está no cofre. undefined em runtime vira erro em lint.

Amigo do Turborepo

Os valores vão pra .env no disco. As chaves env e globalEnv do Turborepo leem do mesmo jeito. O hash de cache não muda.

O que você ganha

envshed init detecta workspaces e sugere um config
Escopo de chaves por workspace — nada de STRIPE_SECRET_KEY vazando pro bundle do frontend
Overrides por usuário junto dos valores compartilhados — sua DATABASE_URL local continua local
Funciona com pnpm workspaces, Turborepo, Nx e Lerna
Trilha de auditoria no nível do workspace — saiba quem puxou o que, onde

Perguntas específicas de monorepo

Preciso de uma conta por pacote?

Não. Uma organização, um projeto, um ambiente. O config declara o que cada workspace lê. Pacotes são só agrupamentos de chaves dentro do mesmo cofre.

Respeita o hash de cache do Turborepo?

Respeita. Os secrets vão pra .env no disco. As chaves env e globalEnv do Turbo leem de lá. O comportamento de cache é o mesmo que você tinha antes do Envshed.

Pacotes diferentes podem usar ambientes diferentes ao mesmo tempo?

Podem. Roda envshed pull --workspace apps/api --env staging e envshed pull --workspace apps/web --env development lado a lado.

E se meu monorepo tem 80 pacotes?

O config continua declarativo e diffável. Dá pra gerar a partir dos package.json na CI se quiser manter automatizado.

Para de diffar .env entre pacotes

Um comando na raiz. Cada workspace puxa exatamente o que precisa.

Começar grátis

Parte do Envshed.