fs.writeFile no Node.js: escrever e criar arquivos

fs.writeFile(path, data, callback) escreve uma string ou um Buffer em um arquivo. Se o arquivo não existe, o Node o cria; se existe, o conteúdo antigo é substituído. fs.writeFileSync(path, data) faz o mesmo e espera a escrita terminar, e fs.appendFile adiciona no final do arquivo em vez de substituir.

const fs = require('fs');

fs.writeFile('hello.txt', 'Hello, file', (err) => {
    if (err) {
        console.error('Write failed:', err.message);
        return;
    }
    console.log('saved');
    console.log(fs.readFileSync('hello.txt', 'utf8'));
});

Ele imprime saved e depois o texto que leu de volta; o callback recebe só um erro (ou null), nunca os dados. Passe 42 no lugar da string e a chamada lança TypeError: os dados precisam ser uma string ou um Buffer.

writeFile, writeFileSync e fs/promises

As três formas recebem os mesmos argumentos e mudam no jeito de esperar o resultado.

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

fs.writeFileSync('a.txt', 'one');            // blocks, throws on error

fs.writeFile('b.txt', 'two', (err) => {});   // callback with err

await fsp.writeFile('c.txt', 'three');       // promise, use in async code

Use writeFileSync em scripts e código de inicialização, e a versão com promise em servidores, onde uma escrita síncrona bloqueia todas as outras requisições até o disco terminar. A página do fs/promises mostra o resto da API com promises.

Adicionar ao arquivo com appendFile

writeFile substitui o arquivo inteiro. Para adicionar uma linha a um log, use appendFile, que também cria o arquivo na primeira vez.

const fs = require('fs');

fs.writeFileSync('log.txt', 'first\n');
fs.writeFileSync('log.txt', 'second\n');
console.log(JSON.stringify(fs.readFileSync('log.txt', 'utf8')));

fs.appendFileSync('log.txt', 'third\n');
fs.appendFileSync('log.txt', 'fourth\n');
console.log(JSON.stringify(fs.readFileSync('log.txt', 'utf8')));

A primeira leitura imprime "second\n", porque o segundo writeFileSync substituiu first, e a segunda imprime "second\nthird\nfourth\n" (o JSON.stringify deixa as quebras de linha visíveis). Coloque o \n você mesmo: nenhuma das duas funções adiciona.

Não sobrescrever: a opção flag

O terceiro argumento pode ser um objeto de opções. A flag decide o que acontece com um arquivo existente. 'wx' significa "escreva, mas falhe se o arquivo já existir", que é o jeito seguro de criar um arquivo uma única vez.

const fs = require('fs');

function createOnce(file, text) {
    try {
        fs.writeFileSync(file, text, { flag: 'wx' });
        console.log('created', file);
    } catch (err) {
        if (err.code === 'EEXIST') {
            console.log(file, 'already exists, left alone');
        } else {
            throw err;
        }
    }
}

createOnce('id.txt', 'abc123');
createOnce('id.txt', 'zzz999');
console.log(fs.readFileSync('id.txt', 'utf8'));

A segunda chamada falha com EEXIST, então o arquivo continua com abc123. Troque o nome do arquivo da segunda chamada para id2.txt e as duas chamadas imprimem created.

As flags que você mais vai encontrar: 'w' (padrão, substituir), 'a' (adicionar), 'wx' (só criar) e 'ax' (adicionar, mas só em um arquivo novo).

Verificar primeiro com fs.existsSync e depois escrever deixa uma brecha: outro processo pode criar o arquivo entre a verificação e a escrita. 'wx' faz as duas coisas em um passo só.

Escrever JSON em um arquivo

writeFile não aceita objetos. Transforme o objeto em texto com JSON.stringify; o terceiro argumento, 2, indenta a saída para o arquivo ficar legível.

const fs = require('fs');

const settings = { theme: 'dark', fontSize: 14, plugins: ['git', 'lint'] };

fs.writeFileSync('settings.json', JSON.stringify(settings, null, 2));

console.log(fs.readFileSync('settings.json', 'utf8'));

const loaded = JSON.parse(fs.readFileSync('settings.json', 'utf8'));
console.log(loaded.plugins.length);

O arquivo guarda o objeto em várias linhas indentadas, e fazer o parse de volta dá um objeto igual, então a última linha imprime 2. Passe o objeto sem JSON.stringify e a chamada lança TypeError.

Crie a pasta antes com mkdir

writeFile cria arquivos, não pastas. Escrever em reports/2026/june.txt quando reports não existe falha com ENOENT. Crie o caminho antes com mkdir e { recursive: true }, que cria todas as pastas que faltam e não faz nada se elas já existem.

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

async function main() {
    try {
        await fs.writeFile('reports/2026/june.txt', 'sales: 12');
    } catch (err) {
        console.log('first try:', err.code);
    }

    await fs.mkdir('reports/2026', { recursive: true });
    await fs.writeFile('reports/2026/june.txt', 'sales: 12');

    console.log(await fs.readdir('reports/2026'));
}
main();

A primeira escrita falha com ENOENT; depois do mkdir, a mesma escrita funciona e readdir lista [ 'june.txt' ]. Em código real, monte esses caminhos com path.join para que funcionem no Windows também.

Erros comuns

Achar que o arquivo está escrito logo depois da chamada. fs.writeFile retorna antes de os dados estarem no disco. Leia o arquivo ou comece o próximo passo dentro do callback, ou dê await na versão com promise.

Perder dados escrevendo em um loop. Chamar writeFile uma vez por item substitui o arquivo a cada vez, e só sobra o último item. Use appendFile, ou monte a string inteira e escreva uma vez.

Escrever [object Object]. Passar um objeto por String() ou por uma template literal escreve [object Object]. Use JSON.stringify.