Virtual File System (vfs.js)

💡 Overview

In a dynamic React framework, page routing and parallel slots resolution require scanning file structures continuously (e.g. searching for page.tsx, layout.tsx, or error.tsx). In production, checking the physical storage drive on every user request introduces I/O latency bottlenecks.

The vfs.js file exposes a Virtual File System wrapper. In production, it crawls the src/ directory once at startup and caches the folder structure in memory.

📊 VFS Operational Flow

The flowchart below shows how the virtual filesystem changes behavior based on the environment:

⚡ Filesystem Optimizations

The dual-mode design optimizes both speed and developer experience:

• Production Cache: During startup, buildVfs() builds a memory map containing folder trees and file states. Requests querying existsSync() or readdirSync() read directly from memory, avoiding disk I/O.
• Development Live Queries: In development, caching files in memory would prevent hot-reloading from detecting new page files immediately. To resolve this, the wrapper bypasses the cache in development, querying the physical disk in real-time.

🎯 Calling Modules & Contexts

To maintain high throughput and prevent disk seek latencies, other framework core modules query the in-memory virtual filesystem instead of Node's native fs module:

• get-file-path-and-dynamic-params.js (Path Resolver): The main router engine maps request URLs to physical file structures. It imports vfs.js's cached existsSync and readdirSync helpers to locate catch-all parameters and route groups instantly.
• get-jsx.js (RSC Tree Builder): When resolving components to construct React Server Component JSX trees, it queries vfs.js to verify component file paths (such as dynamic layouts or pages) before importing them.
• get-error-jsx.js (Error Boundary Handler): Crawls up folders to check for boundary files (like error.tsx or not-found.tsx) using vfs.js's cache, serving custom layout errors cleanly.

⚙️ Complete Code Walkthrough

Below is the full, complete code of vfs.js:

const fs = require("fs");
const path = require("path");

const isDevelopment = process.env.NODE_ENV !== "production";
const vfs = {};

// 1. Recursively build file metadata map in memory
function buildVfs(dir) {
  if (!fs.existsSync(dir)) return;
  const entries = fs.readdirSync(dir, { withFileTypes: true });
  const children = [];

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);
    const isDirectory = entry.isDirectory();
    children.push({
      name: entry.name,
      isDirectory
    });
    if (isDirectory) {
      buildVfs(fullPath);
    } else {
      vfs[fullPath] = { type: "file" };
    }
  }

  vfs[dir] = {
    type: "directory",
    children
  };
}

// 2. Production Warmup: Crawl the source directory at startup
if (!isDevelopment) {
  const srcDir = path.resolve(process.cwd(), "src");
  buildVfs(srcDir);
}

// 3. Optimized existsSync wrapper
function existsSync(filePath) {
  if (isDevelopment) {
    return fs.existsSync(filePath); // Live query in dev
  }
  const normalized = path.resolve(filePath);
  return !!vfs[normalized]; // Fast memory map query in prod
}

// 4. Optimized readdirSync wrapper
function readdirSync(dirPath, options) {
  if (isDevelopment) {
    return fs.readdirSync(dirPath, options);
  }
  const normalized = path.resolve(dirPath);
  const entry = vfs[normalized];
  if (!entry || entry.type !== "directory") {
    throw new Error(`ENOTDIR: not a directory, readdir '${dirPath}'`);
  }

  if (options && options.withFileTypes) {
    return entry.children.map(child => ({
      name: child.name,
      isDirectory: () => child.isDirectory,
      isFile: () => !child.isDirectory
    }));
  }
  return entry.children.map(child => child.name);
}

module.exports = {
  existsSync,
  readdirSync
};