Working with the Node.js File System Module

The Node.js file system module (fs) gives your Express server the ability to read files, write files, create directories, and check if paths exist. In MERN development you will use the file system module more than you might expect — reading .env files, writing logs, handling uploaded images saved to disk, serving static assets, and reading email templates from HTML files. In this lesson you will learn the modern fs/promises API, understand when to use it, and build practical patterns you will reuse throughout the series.

fs vs fs/promises — Which to Use #

Core fs/promises Operations #

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

// ── Read a file ───────────────────────────────────────────────────────────────
async function readConfig() {
  try {
    const filePath = path.join(__dirname, 'config.json');
    const raw      = await fs.readFile(filePath, 'utf8');
    return JSON.parse(raw);
  } catch (err) {
    if (err.code === 'ENOENT') {
      console.error('Config file not found');
      return null;
    }
    throw err;
  }
}

// ── Write a file ──────────────────────────────────────────────────────────────
async function writeLog(message) {
  const logPath = path.join(__dirname, 'logs', 'app.log');
  const entry   = `[${new Date().toISOString()}] ${message}\n`;
  await fs.appendFile(logPath, entry, 'utf8');
}

// ── Check if a file exists ────────────────────────────────────────────────────
async function fileExists(filePath) {
  try {
    await fs.access(filePath);
    return true;
  } catch {
    return false;
  }
}

// ── Create a directory (and any missing parents) ──────────────────────────────
async function ensureUploadDir(dirPath) {
  await fs.mkdir(dirPath, { recursive: true });
  // recursive: true → no error if directory already exists
}

// ── Delete a file ─────────────────────────────────────────────────────────────
async function deleteUpload(filename) {
  const filePath = path.join(__dirname, 'uploads', path.basename(filename));
  await fs.unlink(filePath);
}

Reading Email Templates from Files #

// A practical MERN use case — loading HTML email templates from disk
// server/src/utils/emailTemplate.js

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

/**
 * Loads an HTML template file and replaces {{VARIABLE}} placeholders.
 * @param {string} templateName - filename without extension e.g. 'welcome'
 * @param {object} variables    - e.g. { NAME: 'Jane', LINK: 'https://...' }
 */
async function loadTemplate(templateName, variables = {}) {
  const templatePath = path.join(__dirname, '../templates', `${templateName}.html`);
  let html = await fs.readFile(templatePath, 'utf8');

  for (const [key, value] of Object.entries(variables)) {
    html = html.replaceAll(`{{${key}}}`, value);
  }

  return html;
}

module.exports = { loadTemplate };

Handling File Uploads — Saving to Disk #

// When Multer saves an uploaded file, you sometimes need to rename or move it
const fs   = require('fs/promises');
const path = require('path');

async function saveUploadedFile(tempPath, originalName, userId) {
  // Create user-specific upload directory
  const uploadDir = path.join(__dirname, '..', 'uploads', userId.toString());
  await fs.mkdir(uploadDir, { recursive: true });

  // Sanitise the filename — remove directory traversal characters
  const safeName   = path.basename(originalName);
  const finalPath  = path.join(uploadDir, `${Date.now()}-${safeName}`);

  // Move from temp location to final destination
  await fs.rename(tempPath, finalPath);

  return finalPath;
}

path Module — Essential Methods #

Common Mistakes #

Mistake 1 — Using fs.existsSync() in route handlers #

❌ Wrong — synchronous existence check blocks the event loop:

if (fs.existsSync(uploadPath)) { // blocks!
  fs.unlinkSync(uploadPath);     // also blocks!
}

✅ Correct — use async versions:

try {
  await fs.access(uploadPath);   // throws if file does not exist
  await fs.unlink(uploadPath);   // delete it
} catch { /* file did not exist — that is fine */ }

Mistake 2 — Building paths with string concatenation #

❌ Wrong — hardcoded forward slashes break on Windows:

const filePath = __dirname + '/uploads/' + filename; // breaks on Windows

✅ Correct — use path.join() for cross-platform compatibility:

const filePath = path.join(__dirname, 'uploads', filename); // works everywhere ✓

Mistake 3 — Not handling ENOENT errors #

❌ Wrong — letting a missing file throw an unhandled error to the client:

const data = await fs.readFile(path);
// If file is missing → UnhandledPromiseRejection → server crash or 500 error

✅ Correct — check the error code and respond appropriately:

try {
  const data = await fs.readFile(filePath, 'utf8');
  res.json({ data });
} catch (err) {
  if (err.code === 'ENOENT') return res.status(404).json({ message: 'File not found' });
  next(err); // unexpected error — pass to global error handler
}

Quick Reference #