Trabalhando com o sistema de arquivos em JavaScript: guia completo sobre Node.js

Trabalhando com o sistema de arquivos em JavaScript (Node.js)

No desenvolvimento web moderno, o JavaScript há muito ultrapassou os limites do navegador. Graças à plataforma Node.js, os desenvolvedores obtiveram a capacidade de criar aplicações server-side, trabalhar com bancos de dados e, claro, interagir com o sistema de arquivos. Saber ler, escrever, deletar e mover arquivos é uma das habilidades-chave de qualquer desenvolvedor backend. Neste artigo, vamos detalhar como trabalhar com o sistema de arquivos em JavaScript no Node.js, usando o módulo nativo fs e sua versão moderna baseada em promises fs/promises.

O material será útil tanto para iniciantes que estão começando a estudar Node.js, quanto para desenvolvedores experientes que desejam sistematizar seus conhecimentos. Todos os exemplos de código podem ser executados no seu ambiente de desenvolvimento.

Importando o módulo fs e métodos principais

Para trabalhar com o sistema de arquivos no Node.js, utiliza-se o módulo nativo fs (file system). Ele não precisa ser instalado separadamente — está disponível imediatamente após a instalação do Node.js. Ele é importado da forma padrão:

const fs = require('fs');

No entanto, no JavaScript moderno (ES6+) e Node.js (a partir da versão 14), recomenda-se usar a sintaxe de ES modules e trabalhar com a versão baseada em promises do fs/promises. Isso permite evitar o "callback hell" e escrever um código assíncrono mais limpo usando async/await.

import * as fs from 'fs/promises';// ouconst fs = require('fs/promises');

Os principais métodos do módulo fs dividem-se em três categorias:

• Síncronos — bloqueiam o fluxo de execução (por exemplo, fs.readFileSync()). São usados raramente, principalmente em scripts de inicialização.
• Assíncronos com callbacks — estilo tradicional do Node.js (por exemplo, fs.readFile()).
• Assíncronos baseados em promises — estilo moderno (fs/promises). Recomendado para a maioria das tarefas.

Leitura de arquivos no Node.js

Vamos começar pela ação mais comum — ler o conteúdo de um arquivo. Veremos duas abordagens: usando callbacks e usando promises.

Leitura via callbacks (forma tradicional)

const fs = require('fs');

fs.readFile('example.txt', 'utf8', (err, data) => {  if (err) {    console.error('Erro ao ler o arquivo:', err);    return;  }  console.log('Conteúdo do arquivo:', data);});

Observe: passamos a codificação 'utf8' como segundo argumento. Se não for especificada, os dados serão retornados como um buffer binário (Buffer).

Leitura via promises (forma recomendada)

import { readFile } from 'fs/promises';

async function readExample() {  try {    const data = await readFile('example.txt', 'utf8');    console.log('Conteúdo do arquivo:', data);  } catch (err) {    console.error('Erro ao ler o arquivo:', err);  }}

readExample();

O código ficou mais limpo e compreensível. Os erros são tratados com try/catch, o que é familiar para desenvolvedores acostumados com outras linguagens.

Escrevendo dados em um arquivo

Escrever em um arquivo é a segunda operação mais importante. No Node.js, existem dois métodos principais: writeFile (sobrescreve o arquivo) e appendFile (adiciona dados ao final do arquivo).

Sobrescrevendo um arquivo

import { writeFile } from 'fs/promises';

async function writeExample() {  try {    await writeFile('output.txt', 'Olá, mundo!', 'utf8');    console.log('Arquivo escrito com sucesso');  } catch (err) {    console.error('Erro ao escrever:', err);  }}

writeExample();

Se o arquivo output.txt não existir, ele será criado automaticamente. Se existir, seu conteúdo será completamente sobrescrito.