Configuração Node.js: dotenv, convict, nconf

Configuração de aplicações JavaScript (Node.js): melhores bibliotecas e práticas

Qualquer aplicação Node.js séria requer um sistema de configuração flexível e seguro. Senhas de bancos de dados, chaves de API, portas de servidores, níveis de registro — todos esses parâmetros devem estar separados do código, ser facilmente alteráveis em diferentes ambientes (desenvolvimento, teste, produção) e, o mais importante, não devem entrar no sistema de controle de versão.

Neste artigo, vamos examinar as três bibliotecas mais populares para gerenciamento de configuração em Node.js: dotenv, convict e nconf. Você aprenderá como configurar aplicações corretamente, evitar erros comuns e escolher a ferramenta adequada para suas necessidades.

1. dotenv — simplicidade e segurança

dotenv é a biblioteca mais popular para carregar variáveis de ambiente a partir de um arquivo .env. Sua principal vantagem é o minimalismo. Basta criar um arquivo .env, adicionar seus parâmetros, e a biblioteca os carrega em process.env.

Instalação e uso básico

npm install dotenv

Crie um arquivo .env na raiz do projeto:

PORT=3000DB_HOST=localhostDB_USER=adminDB_PASS=supersecretNODE_ENV=development

No início da sua aplicação (geralmente em app.js ou index.js), adicione:

require('dotenv').config();

const express = require('express');const app = express();

const port = process.env.PORT || 3000;

app.listen(port, () => {  console.log(`Servidor iniciado na porta ${port}`);});

Regras importantes ao trabalhar com dotenv

Nunca commite o arquivo .env no Git. Adicione-o ao .gitignore.
Crie um arquivo .env.example com um modelo de todas as variáveis (sem valores reais). Isso ajudará novos desenvolvedores a se familiarizarem rapidamente.
Para produção, use variáveis de ambiente reais configuradas no servidor. O dotenv é necessário apenas para desenvolvimento.
Não armazene estruturas de dados complexas no .env — apenas strings e números.

2. convict — validação e esquemas

Se o dotenv resolve o problema "como carregar", o convict responde à pergunta "como verificar e estruturar". Esta biblioteca permite definir um esquema de configuração com tipos de dados, valores padrão e regras de validação.

Instalação e exemplo de esquema

npm install convict

const convict = require('convict');

const config = convict({  env: {    doc: 'Ambiente da aplicação',    format: ['production', 'development', 'test'],    default: 'development',    env: 'NODE_ENV'  },  server: {    port: {      doc: 'Porta para o servidor HTTP',      format: 'port',      default: 3000,      env: 'PORT'    }  },  db: {    host: {      doc: 'Host do banco de dados',      format: String,      default: 'localhost',      env: 'DB_HOST'    },    password: {      doc: 'Senha do BD',      format: String,      default: '',      env: 'DB_PASS',      sensitive: true // não exibir em logs    }  }});

// Carregamos os valoresconfig.validate({ allowed: 'strict' });

module.exports = config;

Vantagens do convict

Validação automática — se no .env houver uma string em vez de um número, você receberá um erro ao iniciar.
Documentação — o campo doc serve como documentação embutida.
Segurança — campos marcados com sensitive: true não são exibidos nos logs.
Suporte a estruturas aninhadas — útil para configurações complexas.

3. nconf — hierarquia de fontes

nconf

Também na biblioteca

vcpkg para C++: guia completo com exemplos práticos Envio de SMS em PHP: Visão Geral das Bibliotecas de API para Integração Filas de Tarefas em Swift: GCD, OperationQueue e Combine para iOS/macOS Processamento JSON em Go (Golang): guia completo com exemplos Aprendizado de Máquina em JavaScript: bibliotecas para Node.js — visão geral e exemplos