Processamento de Argumentos de CLI em Node.js com util.parseArgs

Analisar manualmente os argumentos de linha de comando extraídos de process.argv com manipulação de arrays é um processo verboso e sujeito a erros. O uso da função nativa util.parseArgs resolve essa complexidade ao transformar a lista de argumentos em um objeto estruturado de opções e posicionais com validação de tipos integrada.

JavaScript

const { parseArgs } = require('util');

/**
 * Define o esquema de opções aceitas pelo script da CLI
 */
const opcoesConfig = {
  ambiente: {
    type: 'string',
    short: 'a',
    default: 'desenvolvimento',
  },
  porta: {
    type: 'string',
    short: 'p',
    default: '3000',
  },
  verbose: {
    type: 'boolean',
    short: 'v',
    default: false,
  },
};

// Executa o parser omitindo os dois primeiros itens padrão do process.argv (executável e caminho do arquivo)
const { values: opcoes, positionals: posicionais } = parseArgs({
  args: process.argv.slice(2),
  options: opcoesConfig,
  allowPositionals: true,
});

// --- Exemplo Prático de Uso ---
console.log('--- Configurações da CLI ---');
console.log(`Ambiente: ${opcoes.ambiente}`);
console.log(`Porta: ${opcoes.porta}`);
console.log(`Modo Verboso: ${opcoes.verbose ? 'Ativado' : 'Desativado'}`);
console.log('Argumentos Posicionais:', posicionais);

// Para testar via terminal, execute:
// node script.js -a producao -p 8080 -v build deploy

Pontos-chave

• Substituição de Libs Externas: O módulo nativo util.parseArgs (estável no Node.js v18.3.0+) elimina a necessidade de dependências de terceiros como yargs ou commander para projetos e scripts CLI simples.
• Filtro Obrigatorio process.argv.slice(2): É necessário remover as duas primeiras posições do array original (process.execPath e o caminho do arquivo .js) para processar apenas os argumentos enviados pelo usuário.
• Suporte a Aliases Curtos (short): Permite mapear atalhos de um único caractere (ex: -v para --verbose ou -p para --porta), oferecendo flexibilidade na digitação no terminal.
• Controle de Argumentos Posicionais: A flag allowPositionals: true habilita a captura de valores sem nome que não pertençam a nenhuma opção com hífen, organizando-os em um array separado.