Variáveis de ambiente no arquivo .env são essenciais para configurar a aplicação, mas têm um grande problema: não têm autocomplete. E o pior? Você só descobre que cometeu um erro quando a aplicação já quebrou — seja uma API key faltando ou credenciais erradas.

Imagine a situação: ao iniciar o app, do nada, aparece um erro 403 porque sua API key está errada. Ou talvez o banco de dados nem conecte porque as credenciais estão erradas. Encontrar esses erros é uma missão, tudo porque não dá pra validar as variáveis de ambiente logo de cara. É uma bagunça.

Vejamos um arquivo .env típico:

API_KEY=12345
DB_USER=petisco_de_frango
DB_PASS=Petisco_de_frango_senha

Provavelmente você tem algo parecido, com chaves para APIs, credenciais do banco e talvez até uns flags de features. Parece simples, mas muita coisa pode dar errado. E se alguém definir DB_PASS como uma string vazia? E se API_KEY estiver faltando?

É aí que entra o Zod.

Biblioteca Zod

Zod é uma biblioteca de TypeScript usada para definir e validar schemas. Com ela, podemos especificar o formato exato dos dados — incluindo quais campos devem existir, seus tipos e regras adicionais. Se os dados não seguirem essas especificações, o Zod avisa você.

Validando o .env com o Zod

Como o .env tem uma estrutura clara — com variáveis bem definidas e seus respectivos tipos —, podemos usar o Zod para criar um schema que garante que essas variáveis estejam no formato correto.

Primeiro, defina um schema para o seu .env:

const envSchema = z.object({
  API_KEY: z.string().min(1, "API_KEY é obrigatória"),
  DB_USER: z.string().min(1, "DB_USER é obrigatório"),
  DB_PASS: z.string().min(1, "DB_PASS é obrigatório"),
});

Aqui, usamos o Zod para garantir que API_KEY, DB_USER e DB_PASS sejam strings não vazias. Se qualquer uma delas estiver faltando ou errada, o Zod vai dar um toque.

Agora, vamos validar essas variáveis:

const parsedEnv = envSchema.safeParse(process.env);

if (!parsedEnv.success) {
  console.error('Variáveis de ambiente inválidas:', parsedEnv.error.format());
  process.exit(1);
}

Usamos o safeParse para checar se process.env está de acordo com o schema. Se não estiver, ele mostra os erros e encerra a aplicação.

Por fim, podemos usar as variáveis validadas com segurança:

export const env = parsedEnv.data;

Depois da validação, parsedEnv.data contém os valores seguros para usar na aplicação. Assim, você garante que suas variáveis de ambiente estejam sempre corretas, evitando que sua aplicação quebre de forma inesperada.

Usando default() para Variáveis de Ambiente Opcionais

Nem sempre todas as variáveis do .env precisam ser obrigatórias. Algumas delas podem ter valores padrão e só serão usadas se não forem definidas. Um exemplo clássico disso é a porta do servidor, PORT.

Em um ambiente de desenvolvimento, você pode querer que o servidor rode em uma porta padrão, como 3000, caso a variável PORT não esteja configurada no .env. Já em ambientes de produção, como em um serviço de hospedagem ou nuvem, a porta geralmente é definida pela própria plataforma de deploy, e não manualmente no .env. Nesses casos, a aplicação usa o valor fornecido pela plataforma, mas se esse valor não for passado, é importante que o servidor saiba qual porta usar por padrão.

É aí que o método default() do Zod entra em cena. Ele permite definir um valor padrão para uma variável de ambiente, garantindo que, mesmo que a variável PORT não esteja presente, a aplicação funcione com o valor que você escolher, como 3000.

Vamos adicionar a variável PORT ao nosso esquema de validação e definir um valor padrão:

const envSchema = z.object({
  PORT: z.number().default(3000), 
});

Com isso, a variável de ambiente PORT vai ter o valor padrão de 3000 caso não esteja definida no arquivo .env.

Conclusão

Validar as variáveis de ambiente antes de executar a aplicação elimina uma série de erros difíceis de debugar. Em vez de torcer para que as API keys e credenciais estejam corretas, o Zod garante que tudo esteja certo na inicialização.

Por exemplo, se alguém esquecer de definir a API_KEY ou deixá-la vazia, sem o Zod, sua aplicação quebraria quando fosse tentar fazer uma requisição. Com o Zod, você recebe um erro claro logo de cara:

Variáveis de ambiente inválidas: {
  API_KEY: ["API_KEY é obrigatória"]
}

Sem mistério. Você recebe um feedback imediato e ainda ganha variáveis de ambiente tipadas, garantindo que você sempre trabalhe com a configuração certa.