Webpack 5 persistent caching is preventing code changes from loading during development. When you modify a file, the old cached version continues to be served instead of the new code.

This was discovered during the ComponentsPanel React migration (TASK-004B) and is documented in: dev-docs/tasks/phase-2/TASK-004B-componentsPanel-react-migration/STATUS-BLOCKED.md

Symptoms

You modify a TypeScript/JavaScript file
You rebuild or let hot reload trigger
The browser shows the OLD code, not your changes
Console may show stale behavior
console.log statements you add don't appear

Impact

Without fixing this, you cannot:

Test any code changes reliably
Develop any new features
Debug existing issues
Verify that fixes work

Investigation Steps

1. Locate Webpack Configuration

# Find webpack config files
find packages -name "webpack*.js" -o -name "webpack*.ts"

# Common locations:
# packages/noodl-editor/webpack.config.js
# packages/noodl-editor/webpack.renderer.config.js

2. Check Current Cache Settings

Look for:

module.exports = {
  cache: {
    type: 'filesystem',  // This is the culprit
    // ...
  }
}

3. Verify It's a Caching Issue

# Clear all caches and rebuild
rm -rf node_modules/.cache
rm -rf packages/noodl-editor/node_modules/.cache
npm run build -- --no-cache

If changes appear after clearing cache, caching is confirmed as the issue.

Solution Options

Option A: Disable Persistent Caching in Dev (Recommended)

// webpack.config.js
module.exports = (env) => ({
  // Only use filesystem cache in production
  cache: env.production ? {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename],
    },
  } : false,  // No caching in development
  
  // ... rest of config
});

Pros: Simple, guaranteed to work
Cons: Slower dev builds (but correctness > speed)

Option B: Configure Proper Cache Invalidation

// webpack.config.js
module.exports = {
  cache: {
    type: 'filesystem',
    version: `${Date.now()}`,  // Force cache bust
    buildDependencies: {
      config: [__filename],
      // Add all config files that should invalidate cache
    },
    // Invalidate on file changes
    managedPaths: [],
    immutablePaths: [],
  },
};

Pros: Keeps caching benefits when appropriate
Cons: More complex, may still have edge cases

Option C: Memory Cache Only

// webpack.config.js
module.exports = {
  cache: {
    type: 'memory',
    maxGenerations: 1,
  },
};

Pros: Fast rebuilds within session, no persistence bugs
Cons: Every new terminal session starts cold

Implementation Steps

Identify all webpack config files in the project
Check if there are separate dev/prod configs
Implement Option A (safest starting point)
Test the fix:
- Make a visible change to a component
- Rebuild
- Verify change appears in browser
Test hot reload:
- Start dev server
- Make change
- Verify hot reload picks it up
Document the change in LEARNINGS.md

Verification Checklist

Code changes appear after rebuild
Hot reload reflects changes immediately
Console.log statements added to code appear in browser console
No stale code behavior
Build times acceptable (document before/after if significant)
Works across terminal restarts
Works after system restart

Files Likely to Modify

packages/noodl-editor/webpack.config.js
packages/noodl-editor/webpack.renderer.config.js
packages/noodl-editor/webpack.main.config.js (if exists)

TASK-004B ComponentsPanel migration blocked by this
Any future development work blocked by this
PREREQ-002, PREREQ-003, PREREQ-004 all blocked by this

Success Criteria

Can modify any TypeScript/JavaScript file
Changes appear immediately after rebuild
Hot reload works correctly
No need to manually clear caches
Works consistently across multiple dev sessions

README.md

PREREQ-001: Fix Webpack 5 Persistent Caching

Overview

The Problem