fs.writeFile in Node.js: scrivere, aggiungere e creare file

fs.writeFile(path, data, callback) scrive una stringa o un Buffer in un file. Se il file non esiste, Node lo crea; se esiste, il vecchio contenuto viene sostituito. fs.writeFileSync(path, data) fa lo stesso e aspetta che la scrittura sia finita, mentre fs.appendFile aggiunge in fondo al file invece di sostituirlo.

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'));
});

Stampa saved e poi il testo riletto; la callback riceve solo un errore (o null), mai i dati. Passa 42 al posto della stringa e la chiamata lancia un TypeError: i dati devono essere una stringa o un Buffer.

writeFile, writeFileSync e fs/promises

Le tre forme ricevono gli stessi argomenti e cambiano nel modo in cui aspetti il risultato.

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

Usa writeFileSync negli script e nel codice di avvio, e la versione a promise nei server, dove una scrittura sincrona blocca tutte le altre richieste finché il disco non ha finito. La pagina su fs/promises mostra il resto dell'API a promise.

Aggiungere a un file con appendFile

writeFile sostituisce tutto il file. Per aggiungere una riga a un log usa appendFile, che crea il file anche la prima volta.

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')));

La prima lettura stampa "second\n", perché il secondo writeFileSync ha sostituito first, e la seconda stampa "second\nthird\nfourth\n" (JSON.stringify rende visibili gli a capo). Aggiungi tu il \n: nessuna delle due funzioni lo fa.

Non sovrascrivere: l'opzione flag

Il terzo argomento può essere un oggetto di opzioni. Il suo flag decide cosa succede a un file esistente. 'wx' significa "scrivi, ma fallisci se il file esiste già", che è il modo sicuro per creare un file una volta sola.

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'));

La seconda chiamata fallisce con EEXIST, quindi il file contiene ancora abc123. Cambia il nome del file della seconda chiamata in id2.txt ed entrambe le chiamate stampano created.

I flag che incontrerai più spesso: 'w' (predefinito, sostituisce), 'a' (aggiunge), 'wx' (solo creazione) e 'ax' (aggiunge, ma solo a un file nuovo).

Controllare prima con fs.existsSync e poi scrivere lascia un buco: un altro processo può creare il file tra il controllo e la scrittura. 'wx' fa entrambe le cose in un solo passaggio.

Scrivere JSON su un file

writeFile non accetta oggetti. Trasformali in testo con JSON.stringify; il terzo argomento, 2, indenta l'output così il file è leggibile.

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);

Il file contiene l'oggetto su più righe indentate, e rileggendolo con il parsing si ottiene un oggetto uguale, quindi l'ultima riga stampa 2. Passa l'oggetto senza JSON.stringify e la chiamata lancia un TypeError.

Creare prima la cartella con mkdir

writeFile crea file, non cartelle. Scrivere su reports/2026/june.txt quando reports non esiste fallisce con ENOENT. Crea prima il path con mkdir e { recursive: true }, che crea tutte le cartelle mancanti e non fa niente se esistono già.

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();

La prima scrittura fallisce con ENOENT; dopo mkdir la stessa scrittura riesce e readdir elenca [ 'june.txt' ]. Nel codice vero costruisci questi path con path.join, così funzionano anche su Windows.

Errori comuni

Dare per scontato che il file sia scritto subito dopo la chiamata. fs.writeFile ritorna prima che i dati siano sul disco. Leggi il file o passa al passaggio successivo dentro la callback, oppure fai await della versione a promise.

Perdere dati scrivendo in un ciclo. Chiamare writeFile una volta per elemento sostituisce il file ogni volta, e resta solo l'ultimo elemento. Usa appendFile, oppure costruisci tutta la stringa e scrivila una volta sola.

Scrivere [object Object]. Passare un oggetto a String() o a un template literal scrive [object Object]. Usa JSON.stringify.