El sistema de archivos: leer y escribir con fs/promises

Lees y escribes archivos con el módulo fs/promises y construyes rutas fiables gracias al módulo path.

8 min · 3 preguntas

En el navegador, JavaScript no tiene permiso para tocar los archivos de tu disco: es una cuestión de seguridad. Node, en cambio, se ejecuta directamente en tu máquina y puede leer y escribir archivos gracias al módulo fs (file system, sistema de archivos). Usaremos su versión moderna, fs/promises, en la que cada función devuelve una promesa - ya sabes esperarlas con await, visto en el curso de JavaScript. Fíjate en el prefijo node: de las importaciones: deja claro que el módulo proviene del propio Node, no de node_modules. Y buenas noticias: en un módulo ES, await funciona directamente a nivel del archivo, sin una función que lo envuelva.

JAVASCRIPT

import { writeFile } from "node:fs/promises";

await writeFile("notes.txt", "First note\n");
console.log("File created!");

writeFile crea el archivo notes.txt si no existe, con el texto que se le pasa como segundo parámetro.

Si notes.txt ya existe, writeFile sobrescribe todo su contenido sin avisar. Para añadir texto al final de un archivo sin borrar lo que ya está ahí, usa appendFile, disponible en el mismo módulo.

Para leer, la misma lógica con readFile. Su segundo parámetro es esencial: utf8 designa la codificación, es decir, la forma de traducir los bytes almacenados en el disco a texto legible. Si lo omites, Node devuelve un objeto Buffer - bytes en bruto - en lugar de una cadena de caracteres.

JAVASCRIPT

import { readFile } from "node:fs/promises";

const text = await readFile("notes.txt", "utf8");
console.log(text);

El contenido del archivo llega como una cadena de caracteres, lista para manipular.

Hablemos de rutas. Una ruta relativa (notes.txt, data/log.txt) parte de la carpeta actual; una ruta absoluta (C:\... o /home/...) parte de la raíz del disco. Una trampa clásica: Windows separa las carpetas con \, macOS y Linux con /. El módulo path resuelve el problema: path.join ensambla las piezas con el separador correcto, sea cual sea el sistema. Combinémoslo con mkdir, que crea una carpeta.

JAVASCRIPT

import path from "node:path";
import { mkdir, writeFile } from "node:fs/promises";

const file = path.join("data", "log.txt");

await mkdir("data", { recursive: true });
await writeFile(file, "First log\n");
console.log("Written to:", file);

La opción recursive evita un error si la carpeta data ya existe.

Las rutas relativas parten de la carpeta donde ejecutaste el comando node, no de la carpeta donde se encuentra el script. Esta carpeta de partida se llama directorio de trabajo: muéstralo en cualquier momento con process.cwd().

Prueba de conocimientos

Comprueba que has retenido los puntos clave de esta lección.

¿Qué devuelve readFile si omites el segundo parámetro utf8?
- Una cadena vacía
- Un error: la codificación es obligatoria
- Un Buffer, es decir, los bytes en bruto del archivo
¿Qué hace writeFile si el archivo de destino ya existe?
- Reemplaza todo el contenido existente con el nuevo texto
- Añade el nuevo texto al final del archivo
- Se niega a escribir y lanza un error
- Crea automáticamente una copia de seguridad
¿Cuál es la ventaja de path.join para construir una ruta?
- Crea las carpetas que faltan en la ruta
- Ensambla las piezas con el separador correcto para el sistema
- Comprueba que el archivo existe antes de continuar