The fs Module

The fs (file system) module is Node's built-in tool for reading, writing, updating, and deleting files and directories on disk, available in synchronous, callback, and promise-based forms.

Learn The fs Module in our free Node.js course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Node.js course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

By the end of this lesson you'll know how to read a file into a string, write and append data, work with directories, check whether a path exists, and delete files — and you'll understand when to reach for the fast non-blocking promise API instead of the simpler synchronous one.

What You'll Learn in This Lesson

1️⃣ Reading Files

Reading is the most common file operation. There are two main styles. fs.readFileSync is synchronous : it pauses your program until the file is fully read, then hands back the contents. It's easy to reason about, which is why it's fine in short scripts — but it blocks the event loop, so it's a poor fit for servers.

The modern alternative is the promise-based API : import { readFile } from 'node:fs/promises' and then await readFile(...) . It does the same job without freezing everything else. In both cases, pass 'utf8' as the second argument so you get a readable string back instead of a raw Buffer of bytes.

2️⃣ Writing & Appending

Writing comes in two flavours. fs.writeFileSync(path, data) creates the file if it doesn't exist and overwrites it completely if it does — so use it carefully. The promise version, writeFile from node:fs/promises , does the same thing without blocking.

When you want to add to a file rather than replace it — think log files — reach for fs.appendFile (or appendFileSync ). It writes your text onto the end and creates the file first if it isn't there yet.

3️⃣ Directories & Existence

Files live in directories, and fs handles those too. fs.mkdir creates a folder — pass { recursive: true } to build any missing parent folders and to avoid an error if it already exists. fs.readdir lists what's inside a folder as an array of names.

To check whether something is there, fs.existsSync(path) returns a simple true / false . For richer information, fs.stat returns metadata (size, and helpers like isDirectory() ). Finally, fs.unlink deletes a file.

Your turn. The program below works once you fill in the two blanks marked ___ . Follow the 👉 hints, then run it and compare with the expected output.

Mini-Challenge: A Tiny Journal

No blanks this time — just a brief and an outline to keep you on track. Write it yourself, run it, and check your output against the example in the comments. This ties together writing, appending, and reading in one short program.

Common Errors (and the fix)

• "ENOENT: no such file or directory" — Node looked where you pointed and found nothing. The path is usually relative to where you ran the process, not where the file lives. Build an absolute path with __dirname (or import.meta.dirname ) plus path.join , and double-check the filename.
• Got a <Buffer 42 75 79 ...> instead of text? — You forgot the encoding. fs.readFileSync('f.txt') returns raw bytes; add 'utf8' as the second argument to get a string.
• Your server feels frozen under load — A ...Sync call blocks the single event loop, so every other request waits. In servers, switch to the node:fs/promises API with await .
• "EACCES: permission denied" — The file or folder exists, but your process isn't allowed to read or write it. Check ownership and permissions, or write somewhere your user controls (like a temp or project folder).
• "Promise { <pending> } " printed instead of data — You used the promise API but forgot await (and an enclosing async function). Without awaiting, you're logging the promise itself, not its result.

Pro Tips

• 💡 Default to the promise API: node:fs/promises with await reads cleanly and won't block your event loop. Keep the ...Sync calls for tiny startup scripts.
• 💡 Always build paths with the path module: combine __dirname and path.join('data', 'file.txt') so your code works on every operating system.
• 💡 Use the node: prefix ( require('node:fs') ) to make it unmistakable you mean the built-in module, not a package of the same name.

📋 Quick Reference — The fs Module

Task

fs Syntax

Read (sync)

fs.readFileSync(p, 'utf8')

Read (promise)

await readFile(p, 'utf8')

Write

fs.writeFileSync(p, data)

Append

fs.appendFileSync(p, data)

List a directory

fs.readdirSync(d)

Does it exist?

fs.existsSync(p)

Delete a file

fs.unlinkSync(p)

Frequently Asked Questions

🎉 Lesson Complete!

• ✅ fs is Node's built-in module for reading, writing, and deleting files and folders
• ✅ readFileSync(p, 'utf8') returns a string; without 'utf8' you get a Buffer
• ✅ The node:fs/promises API with await is the non-blocking choice for servers
• ✅ writeFile overwrites; appendFile adds to the end
• ✅ mkdir , readdir , existsSync , stat , and unlink handle directories, checks, and deletes
• ✅ Most "ENOENT" errors are really a wrong path — build paths with __dirname
• ✅ Next lesson: Paths & OS — build cross-platform paths and read system info

Practice quiz

Continue this course

• Previous: Core Globals (process, __dirname)
• Next: Paths & OS