Node.js fs Module Pulled into Client Bundle

What Happened

During Phase 4 of the Execution Tracks build, I added getLessonContent() to lib/tracks.ts. This function reads MDX files from the filesystem using fs.readFileSync. It required import fs from 'fs' and import path from 'path' at the top of the file.

lib/tracks.ts was already being imported by components/tracks/track-roadmap.tsx, which is marked 'use client'. When Next.js bundles client components, it follows all imports — including lib/tracks.ts — and tries to include them in the browser bundle.

The build failed immediately:

Module not found: Can't resolve 'fs'
Import trace for requested module:
  ./lib/tracks.ts
  ./components/tracks/track-roadmap.tsx

The Module Boundary Rule

Next.js maintains a strict server/client boundary:

• Server Components and server-only files can use any Node.js API
• Client Components (files with 'use client') and their entire import tree must be browser-compatible
• The boundary is transitive — if track-roadmap.tsx imports lib/tracks.ts, then everything lib/tracks.ts imports must also be browser-safe

The mistake: adding a server-side function (getLessonContent) to a file that was already in a client component's import chain.

The Fix

Split the file along the server/client boundary:

lib/lesson-content.ts (new — server only):

import fs from 'fs'
import path from 'path'

const LESSONS_ROOT = path.join(process.cwd(), 'content', 'lessons')

export function getLessonContent(
  trackId: string, moduleId: string, lessonId: string
): string | null {
  const mdxPath = path.join(LESSONS_ROOT, trackId, moduleId, `${lessonId}.mdx`)
  if (!fs.existsSync(mdxPath)) return null
  return fs.readFileSync(mdxPath, 'utf-8')
}

lib/tracks.ts (updated — fs/path removed):

// Removed:
// import fs from 'fs'
// import path from 'path'
// export function getLessonContent(...) { ... }

The lesson detail page (app/tracks/[track]/[module]/[lesson]/page.tsx) is a Server Component, so it safely imports from lib/lesson-content.ts.

Why This Is Hard to Catch Before Build

Local next dev sometimes tolerates this error — the dev server can be more lenient about module resolution. The failure surfaces during next build when Next.js constructs the full client bundle.

The import chain also obscures the root cause. The error message points to track-roadmap.tsx, but the actual problem is in lib/tracks.ts, one level up the import chain.

Prevention Pattern

1. Never add Node.js built-in imports to a file that any client component imports
2. If a file is used by both server and client code, split it: keep shared types/config in the original, move server-only functions to a new *.server.ts file
3. Name server-only files with a .server.ts suffix — this is a convention that makes the boundary explicit at a glance
4. After adding any new import to a shared lib file, check whether that file is in any client component's import chain