fs.writeFile en Node.js: escribir, añadir y crear archivos

fs.writeFile(path, data, callback) escribe un string o un Buffer en un archivo. Si el archivo no existe, Node lo crea; si existe, el contenido anterior se reemplaza. fs.writeFileSync(path, data) hace lo mismo y espera a que la escritura termine, y fs.appendFile añade al final del archivo en lugar de reemplazarlo.

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

Imprime saved y después el texto que volvió a leer; el callback solo recibe un error (o null), nunca los datos. Pasa 42 en lugar del string y la llamada lanza un TypeError: los datos tienen que ser un string o un Buffer.

writeFile, writeFileSync y fs/promises

Las tres formas reciben los mismos argumentos y se diferencian en cómo esperas el 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

Usa writeFileSync en scripts y código de arranque, y la versión con promesas en servidores, donde una escritura síncrona bloquea todas las demás peticiones hasta que el disco termina. La página de fs/promises muestra el resto de la API de promesas.

Añadir a un archivo con appendFile

writeFile reemplaza el archivo entero. Para añadir una línea a un log, usa appendFile, que además crea el archivo la primera 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')));

La primera lectura imprime "second\n", porque el segundo writeFileSync reemplazó first, y la segunda imprime "second\nthird\nfourth\n" (JSON.stringify hace visibles los saltos de línea). Añade tú el \n: ninguna de las dos funciones lo pone.

No sobrescribir: la opción flag

El tercer argumento puede ser un objeto de opciones. Su flag decide qué pasa con un archivo que ya existe. 'wx' significa "escribe, pero falla si el archivo ya existe", que es la forma segura de crear un archivo una sola 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'));

La segunda llamada falla con EEXIST, así que el archivo sigue conteniendo abc123. Cambia el nombre del archivo de la segunda llamada a id2.txt y las dos llamadas imprimen created.

Los flags que más vas a ver: 'w' (por defecto, reemplazar), 'a' (añadir), 'wx' (solo crear) y 'ax' (añadir, pero solo a un archivo nuevo).

Comprobar primero con fs.existsSync y después escribir deja un hueco: otro proceso puede crear el archivo entre la comprobación y la escritura. 'wx' hace las dos cosas en un solo paso.

Escribir JSON en un archivo

writeFile no acepta objetos. Conviértelos en texto con JSON.stringify; el tercer argumento, 2, indenta la salida para que el archivo se lea bien.

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

El archivo contiene el objeto en varias líneas indentadas, y al parsearlo de nuevo se obtiene un objeto igual, así que la última línea imprime 2. Pasa el objeto sin JSON.stringify y la llamada lanza un TypeError.

Crear antes la carpeta con mkdir

writeFile crea archivos, no carpetas. Escribir en reports/2026/june.txt cuando reports no existe falla con ENOENT. Crea primero la ruta con mkdir y { recursive: true }, que crea todas las carpetas que faltan y no hace nada si ya existen.

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 primera escritura falla con ENOENT; después de mkdir, la misma escritura funciona y readdir lista [ 'june.txt' ]. En código real, construye estas rutas con path.join para que funcionen también en Windows.

Errores comunes

Dar por hecho que el archivo está escrito justo después de la llamada. fs.writeFile devuelve antes de que los datos estén en disco. Lee el archivo o empieza el siguiente paso dentro del callback, o haz await de la versión con promesas.

Perder datos al escribir en un bucle. Llamar a writeFile una vez por elemento reemplaza el archivo cada vez, y solo queda el último elemento. Usa appendFile, o construye el string completo y escríbelo una vez.

Escribir [object Object]. Pasar un objeto por String() o por un template literal escribe [object Object]. Usa JSON.stringify.