Configuração de aplicações TypeScript: bibliotecas e ferramentas

Configuração de aplicações TypeScript: visão geral de ferramentas e bibliotecas

Uma aplicação TypeScript moderna raramente funciona isoladamente. Ela precisa saber a qual banco de dados se conectar, qual porta usar, onde estão as APIs de terceiros e como se comportar em diferentes ambientes (development, staging, production). Uma configuração adequada não é apenas armazenar configurações, mas uma disciplina completa que inclui validação, tipagem e segurança.

Neste artigo, vamos analisar as principais ferramentas e bibliotecas para gerenciamento de configuração em projetos TypeScript, desde soluções simples até padrões industriais.

Por que é necessária uma configuração separada?

Existem várias abordagens para armazenar configurações, e cada uma tem suas desvantagens:

• Hardcode no código-fonte — viola o princípio 12-factor app, a configuração se mistura com o código, impossibilitando alterar o comportamento sem recompilar.
• Variáveis de ambiente (process.env) — forma padrão, mas todos os valores são strings, não há validação, é fácil cometer um erro de digitação.
\
• Arquivos JSON/YAML — convenientes, mas precisam ser versionados com cuidado para não expor segredos no repositório.

O TypeScript adiciona mais uma camada: queremos que a configuração seja estritamente tipada e que os erros sejam detectados em tempo de compilação, e não em tempo de execução.

Bibliotecas para trabalhar com variáveis de ambiente

dotenv

A biblioteca mais popular para carregar variáveis de arquivos .env. Em projetos TypeScript, é usada quase sempre.

// npm install dotenv @types/dotenvimport dotenv from 'dotenv';

dotenv.config(); // carrega .env em process.env

console.log(process.env.PORT); // '3000' — string

Características:

• Funciona com qualquer framework (Express, NestJS, Next.js).
• Suporta vários arquivos (.env.local, .env.production).
• Não realiza validação — apenas carregamento.

env-var

Uma camada sobre process.env que adiciona validação e conversão de tipos diretamente em tempo de execução.

// npm install env-varimport env from 'env-var';

export const config = {    PORT: env.get('PORT').required().asPortNumber(),    DB_HOST: env.get('DB_HOST').required().asString(),    DEBUG: env.get('DEBUG').default('false').asBool(),    API_KEYS: env.get('API_KEYS').asArray()};

Prós: API simples, conversores embutidos (número, porta, booleano, array).
Contras: não há integração com TypeScript no nível de tipos — o resultado ainda é string | number | boolean.

Soluções industriais: convict e node-config

Convict

Biblioteca para descrever um esquema de configuração com validação, valores padrão e suporte a várias fontes (arquivos, env, argumentos de linha de comando).

// npm install convict @types/convictimport convict from 'convict';

const config = convict({    env: {        format: ['production', 'development', 'test'],        default: 'development',        env: 'NODE_ENV'    },    server: {        port: {            format: 'port',            default: 3000,            env: 'PORT'        }    },    db: {        host: {            format: String,            default: 'localhost',            env: 'DB_HOST'        }    }});

config.validate({ allowed: 'strict' }); // lançará um erro se os dados forem inválidos

export default config;

Características do convict:

• Formatos embutidos: port, email, url, int, nat (número natural).
• Leitura automática de process.env e arquivos JSON.
• Suporte a esquemas aninhados.
• Desvant