Noções Básicas de Configuração

8 exemplos para você começar com Configuração para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

npm install zod
npm install -D typescript@5.6 tsx dotenv

O Node 24.18.0 lê process.env em tempo de execução. Os valores de produção vêm da plataforma (k8s, ECS, Fly.io), não de arquivos na imagem.

Exemplos Básicos

1. Configuração Twelve-Factor em Um Módulo

Todas as configurações fluem através de uma única exportação config.

// src/config.ts
import { z } from "zod";
 
const envSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});
 
export const config = envSchema.parse(process.env);

• parse lança um erro na inicialização se DATABASE_URL estiver faltando - falha rápida, não na primeira requisição
• Nenhum outro arquivo lê process.env diretamente
• Testes definem process.env antes de importar config ou usam importação dinâmica após a configuração

Relacionado: Validação com Zod e env-schema - configurações tipadas

2. Separar Segredos de Não-Segredos

Segredos rotacionam com mais frequência e precisam de ACLs mais rigorosas.

const envSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),           // segredo - string de conexão
  STRIPE_SECRET_KEY: z.string().min(1),     // segredo - chave de API
  PUBLIC_WEB_URL: z.string().url(),         // não-segredo - seguro em logs
});

• Nunca registre DATABASE_URL ou chaves de API - censure em serializadores Pino
• Não-segredos podem residir em ConfigMaps; segredos em Vault/SSM/Segredos k8s
• O mesmo módulo Zod pode marcar campos para geradores de documentação

Relacionado: Gerenciadores de Segredos - busca na inicialização

3. Arquivo .env Local Apenas para Desenvolvimento

# .env.example (commitado)
PORT=3000
DATABASE_URL=postgres://localhost:5432/app_dev
LOG_LEVEL=debug

// src/bootstrap-env.ts - importado apenas da entrada de desenvolvimento
import { config as loadEnv } from "dotenv";
if (process.env.NODE_ENV !== "production") {
  loadEnv();
}

• Commite .env.example, nunca .env
• CI e produção injetam variáveis de ambiente da plataforma
• dotenv é uma dependência de desenvolvimento quando possível

Relacionado: dotenv vs Injeção de Plataforma - local vs produção

4. Porta e Ambiente Node Tipados

Evite portas tipadas como string em app.listen.

import { config } from "./config";
 
const app = express();
app.listen(config.PORT, () => {
  console.log(`ouvindo em ${config.PORT} env=${config.NODE_ENV}`);
});

• z.coerce.number() aceita "3000" de variáveis de ambiente string do k8s
• Ramifica o comportamento em config.NODE_ENV, não em process.env.NODE_ENV disperso
• O ambiente test usa URL de banco de dados em memória de segredos da CI

5. Alternâncias de Funcionalidade como Configuração (Estática)

Flags booleanas de variáveis de ambiente para simples chaves de desligamento.

const envSchema = z.object({
  FEATURE_NEW_CHECKOUT: z
    .enum(["true", "false"])
    .default("false")
    .transform((v) => v === "true"),
});

• Flags de ambiente estáticas exigem redeploi para serem alteradas - bom para alternâncias raras
• Para flags por usuário, use um provedor em tempo de execução (LaunchDarkly, Unleash)
• Documente cada flag em .env.example com o proprietário e a data de remoção

Relacionado: Alternâncias de Funcionalidade e em Tempo de Execução - flags dinâmicas

6. Timeouts e Tamanhos de Pool Configuráveis

Ajustes operacionais pertencem à configuração, não a números mágicos codificados.

const envSchema = z.object({
  HTTP_TIMEOUT_MS: z.coerce.number().default(30_000),
  DB_POOL_MAX: z.coerce.number().default(10),
});

• Padrões no esquema Zod documentam linhas de base de produção sensatas
• Substitua em staging para ensaiar modos de falha
• Alerte quando os valores de produção se desviarem dos intervalos documentados

Exemplos Intermediários

7. Singleton de Configuração Preguiçoso com Sobrescrita de Teste

let cached: AppConfig | undefined;
 
export function loadConfig(env = process.env): AppConfig {
  if (!cached) cached = envSchema.parse(env);
  return cached;
}
 
export function resetConfigForTests() {
  cached = undefined;
}

• Testes chamam resetConfigForTests() entre casos
• Produção importa loadConfig() uma vez na inicialização
• Evita analisar env a cada importação durante o hot reload

8. Valide Campos Relacionados com .refine

const envSchema = z
  .object({
    REDIS_URL: z.string().url().optional(),
    CACHE_ENABLED: z.enum(["true", "false"]).transform((v) => v === "true"),
  })
  .refine((e) => !e.CACHE_ENABLED || e.REDIS_URL, {
    message: "REDIS_URL é necessário quando CACHE_ENABLED=true",
  });

• Regras entre campos capturam ambientes de staging mal configurados na inicialização
• Mensagens de erro aparecem nos logs de deploy da CI antes que o tráfego seja roteado
• Combine com Melhores Práticas de Configuração para padrões de equipe

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.