Como Utilizar e Validar Variáveis de Ambiente em TypeScript com Zod ?

TypeScript 2 de Fev de 2024

Texto de Paulo Clemente
Desenvolvedor na Rocketseat

A partir da versão 20.6 do Node.js, uma nova funcionalidade foi introduzida, eliminando a necessidade de utilizar bibliotecas externas como o dotenv para o carregamento automático de variáveis de ambiente a partir de arquivos .env. Este artigo explora como você pode verificar e validar essas variáveis em seu servidor Node.js, garantindo que todas as configurações necessárias estejam presentes e corretas antes de iniciar a aplicação.

Verificando Variáveis de Ambiente

Para começar, é importante entender como testar se as variáveis de ambiente estão sendo carregadas corretamente pelo Node.js. Uma maneira simples de fazer isso é utilizando o objeto global process.env, que armazena todas as variáveis de ambiente disponíveis para a aplicação. Seguindo os passos abaixo, você pode facilmente verificar a presença de variáveis específicas:

Imprimindo Variáveis de Ambiente: Adicione um console.log(process.env) no seu servidor Node.js. Isso irá imprimir no console todas as variáveis de ambiente carregadas.
Verificando uma Variável Específica: Procure pela variável DATABASE_URL no log gerado. A presença desta variável indica que ela foi carregada corretamente.

Para sabe mais sobre como gerenciar variáveis ambiente veja o artigo abaixo:

Caso a variável DATABASE_URL não esteja presente, pode ser necessário configurar explicitamente o caminho do arquivo .env no Node.js. Isso é feito adicionando a flag --env-file .env ao comando de execução do Node.js no seu package.json, conforme mostrado a seguir:

"scripts": {
  "start": "node --env-file .env app.js"
}

Após modificar o script e executar o comando npm start ou yarn start, a variável DATABASE_URL deverá aparecer impressa no console, indicando que foi carregada com sucesso.

Validando Variáveis de Ambiente com Zod

Para assegurar que todas as variáveis de ambiente necessárias estejam não apenas presentes, mas também corretas, você pode utilizar a biblioteca Zod para validação. Antes de tudo, instale o Zod no seu projeto:

npm install zod

O Zod é uma solução poderosa para definir esquemas de validação para suas variáveis de ambiente. Veja um exemplo de como implementar essa validação:

import { z } from 'zod';

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  CLOUDFLARE_ENDPOINT: z.string().url(),
  CLOUDFLARE_ACCESS_KEY_ID: z.string(),
  CLOUDFLARE_SECRET_ACCESS_KEY: z.string(),
});

export const env = envSchema.parse(process.env);

No exemplo acima, definimos um esquema para as variáveis de ambiente esperadas usando o Zod. Esse esquema é utilizado para fazer o parse e validar as variáveis presentes em process.env. Caso alguma variável não esteja presente ou não corresponda ao tipo esperado (por exemplo, uma URL válida), o Zod lançará um erro, indicando exatamente o que está faltando ou incorreto.

A prática de verificar e validar variáveis de ambiente no início do desenvolvimento de uma aplicação é crucial para evitar surpresas desagradáveis e garantir que o ambiente de execução esteja corretamente configurado. Com o suporte nativo do Node.js para carregar variáveis de ambiente e a utilização do Zod para validação, você tem uma combinação poderosa para gerenciar configurações de forma eficiente e segura, facilitando o trabalho em equipe e a manutenção do projeto.

Implementar essa abordagem não apenas melhora a robustez da sua aplicação como também proporciona uma excelente prática de desenvolvimento, assegurando que todos os membros da equipe estejam cientes das dependências de configuração do projeto desde o início.

Veja na prática: