AI & Agent Dev Bug Sandbox Back to Radar

Turbopack HMR Fails To Update Server Component Using Singleton Registry On MacOS

When using a singleton pattern to register server components, Turbopack HMR does not update the content in the browser, while webpack works correctly. The issue occurs on macOS with Next.js 16.3.0.

mediumConfidence 80%Next.js Affected V16.3.0

Origin Analysis

Turbopack's HMR mechanism does not properly invalidate module-level singleton caches when a module is hot-replaced. The singleton registry retains the old component reference, preventing the updated component from being rendered. Webpack's HMR handles module replacement differently, leading to correct updates.

1. Use a macOS device. 2. Run npm install. 3. Run npm run dev (Turbopack). 4. Edit components/problem-server-component.tsx and save. 5. Observe that the UI does not update immediately. 6. Edit components/working-client-component.tsx and save; observe that client component updates. 7. Stop and run npm run dev:webpack. 8. Repeat step 4 and notice that HMR works with webpack.

Fixing Code Block

// Fix: Remove the singleton registry and directly export/import the component.
// problem-server-component.tsx
export default function ProblemServerComponent() {
  return <div>Updated text from HMR</div>;
}

// page.tsx (or parent component)
import ProblemServerComponent from './problem-server-component';

export default function Page() {
  return <ProblemServerComponent />;
}

Directly exporting and importing the component allows Turbopack to track the module dependency and update the exported reference during HMR. The singleton registry bypasses the module export system, leaving stale references that HMR cannot refresh.

Edge Case Audit

Removing the singleton pattern may eliminate intentional shared state or instance uniqueness. If singleton behavior is required, consider using React's cache() for server components or await an official Turbopack fix. This workaround only affects development HMR and has no impact on production builds. Rollback: revert to the original singleton code after upgrading Next.js to a version that fixes the underlying HMR issue.