Como Criar Estruturas de Pastas Profundas em Node.js com fs.mkdir Recursivo

Tentar criar diretórios aninhados em Node.js sem verificar a existência das pastas pai pode resultar em erros do sistema de arquivos (ENOENT). O uso do parâmetro { recursive: true } no método fs.promises.mkdir resolve esse problema de forma elegante, garantindo a criação de toda a árvore de diretórios sem falhar caso alguma pasta já exista.

JavaScript

const fs = require('fs/promises');
const path = require('path');

/**
 * Cria uma estrutura de diretórios aninhados de forma segura e assíncrona.
 * @param {string} caminhoDiretorio - Caminho completo ou relativo das pastas a criar.
 * @returns {Promise<string|undefined>} Retorna o primeiro diretório criado ou undefined se já existirem.
 */
async function criarEstruturaPastas(caminhoDiretorio) {
  try {
    // A opção recursive garante a criação de pastas pai inexistentes
    const caminhoCriado = await fs.mkdir(caminhoDiretorio, { recursive: true });
    
    console.log(`[Sucesso] Estrutura garantida no caminho: ${caminhoDiretorio}`);
    return caminhoCriado;
  } catch (erro) {
    console.error(`[Erro] Falha ao criar diretórios em ${caminhoDiretorio}:`, erro.message);
  }
}

// --- Exemplo Prático de Uso ---
(async () => {
  // Define um caminho com múltiplos níveis de pastas aninhadas
  const pastaProfunda = path.join(__dirname, 'logs', '2026', 'outubro', 'erros');

  // Executa a criação da estrutura de pastas
  await criarEstruturaPastas(pastaProfunda);
})();

Pontos-chave

• Prevenção de Exceções (EEXIST): Diferente da execução padrão, passar { recursive: true } impede que o Node.js lance um erro caso o diretório final ou as pastas intermediárias já existam no sistema.
• Criação Automática de Pastas Pai: O método gera em cadeia todos os subdiretórios ausentes no caminho fornecido (equivalente ao comando mkdir -p no ecossistema Unix/Linux).
• Compatibilidade com path.join: Recomenda-se construir o caminho das pastas usando o módulo path para evitar falhas de separadores de diretório entre Windows (\) e Linux/macOS (/).
• Sintaxe Assíncrona Moderna: O uso de fs/promises aliado a async/await evita o bloqueio da Event Loop, sendo essencial para operações de I/O em servidores web e APIs de alta concorrência.