Next.js 15 Turbopack IIFE Bug: Why It Happens and How to Fix It

An IIFE that runs correctly in classic bundling can behave inconsistently in Next.js 15 when Turbopack is enabled, especially when the code depends on module evaluation order, browser-only globals, or side effects during import time. The result looks random: the function appears defined, but its immediate execution never produces the expected effect. This tutorial explains the real cause, how to reproduce the failure pattern safely, and the most reliable fixes for production-grade apps.

Understanding the Root Cause

This bug is usually not that JavaScript suddenly stopped supporting IIFEs. The problem is that Turbopack changes how modules are analyzed, transformed, and evaluated during development. In Next.js 15, especially with the App Router, a file can be treated as server code, client code, or shared code depending on where it is imported and whether it includes use client.

An IIFE often assumes one or more of these conditions:

• The module executes immediately on first import.
• The code runs in a browser environment.
• The side effect is preserved and not optimized away.
• The execution order matches the author’s expectation.

With Turbopack, those assumptions can fail for a few technical reasons:

1. Module side effects are handled differently

If your IIFE is only used for a side effect, Turbopack may evaluate the module in a different lifecycle than expected during development, hot reload, or incremental graph updates. That can make the effect appear delayed, skipped, or executed in a context where the result is invisible.

2. Server and client boundaries matter more in Next.js 15

If the IIFE touches window, document, localStorage, or DOM state, and the file is imported from a Server Component, the code may not run in the browser at the moment you expect. Even if the file compiles, import-time side effects are fragile when crossing server/client boundaries.

3. Import-time execution is brittle under HMR

Hot Module Replacement in Turbopack can reevaluate only parts of the graph. If your logic depends on “run once at import time,” development mode may expose behavior that differs from a full page load.

4. Top-level immediate execution is harder to reason about than React lifecycle hooks

An IIFE placed at module scope runs outside React’s lifecycle. In a modern Next.js app, code that mutates browser state is much safer inside useEffect in a client component, where the runtime guarantees browser availability after hydration.

In short, the root cause is typically import-time side effects inside an IIFE colliding with Turbopack’s module evaluation model and Next.js 15 server/client execution boundaries.

Step-by-Step Solution

The most reliable fix is to move the IIFE logic out of top-level module execution and into an explicit runtime path. In most frontend cases, that means a Client Component plus useEffect.

Solution 1: Replace the IIFE with a client-side effect

If your current code looks like this pattern:

(() => {
  console.log('runs immediately');
  document.body.setAttribute('data-test', 'active');
})();

Refactor it into a client component:

'use client';

import { useEffect } from 'react';

export default function BugSafeComponent() {
  useEffect(() => {
    console.log('runs on client after mount');
    document.body.setAttribute('data-test', 'active');
  }, []);

  return <div>Client-safe execution</div>;
}

This fix works because useEffect only runs in the browser, after the component mounts, which avoids import-time ambiguity.

Solution 2: Isolate browser-only logic into a dedicated client module

If you must keep the logic separate, create a helper function instead of using an IIFE.

export function runBrowserInit() {
  if (typeof window === 'undefined') return;

  console.log('safe browser init');
  document.body.setAttribute('data-test', 'active');
}

Then call it from a client component:

'use client';

import { useEffect } from 'react';
import { runBrowserInit } from './browser-init';

export default function Page() {
  useEffect(() => {
    runBrowserInit();
  }, []);

  return <div>Page loaded</div>;
}

Solution 3: Mark the component boundary correctly

If the bug happens because the file is being consumed by a Server Component, ensure the entry component explicitly declares client mode:

'use client';

export default function ClientOnlyWidget() {
  return <div>Client widget</div>;
}

Without use client, import-time code may execute in a server context or be bundled differently than expected.

Solution 4: Dynamically import truly browser-dependent code

For code that should never participate in SSR, use a dynamic import with SSR disabled.

import dynamic from 'next/dynamic';

const ClientWidget = dynamic(() => import('./ClientWidget'), {
  ssr: false,
});

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

This is especially useful when the original IIFE initializes a third-party library that assumes a live DOM.

Solution 5: Test whether Turbopack is the trigger

To confirm the issue is specifically tied to Turbopack mode, run the app without it and compare behavior. If the IIFE works in one mode and fails in the other, that strongly suggests a bundler evaluation difference, not a syntax error in your JavaScript.

Then keep the safer refactor anyway. Even if a framework patch later improves Turbopack behavior, avoiding import-time side effects remains the more maintainable architecture.

Recommended final pattern

'use client';

import { useEffect, useRef } from 'react';

export default function StableInitializer() {
  const hasRun = useRef(false);

  useEffect(() => {
    if (hasRun.current) return;
    hasRun.current = true;

    if (typeof window === 'undefined') return;

    console.log('stable one-time init');
    document.body.dataset.ready = 'true';
  }, []);

  return <div>Initialized safely</div>;
}

This version prevents duplicate client initialization during development quirks and keeps the execution inside React’s supported lifecycle.

Common Edge Cases

Strict Mode causes duplicate development execution

In development, React Strict Mode can intentionally rerun effects to surface unsafe side effects. If you move your IIFE into useEffect and still see double logs, use a guard like useRef when the side effect must only happen once per mount lifecycle.

Third-party packages with top-level side effects

If the issue originates inside an external library, you may not be able to edit its IIFE directly. In that case, load the package only in a client-only boundary using dynamic import or import it inside useEffect.

'use client';

import { useEffect } from 'react';

export default function ThirdPartyLoader() {
  useEffect(() => {
    import('some-browser-only-package').then((mod) => {
      mod.init?.();
    });
  }, []);

  return <div>Loading package</div>;
}

Code works after refresh but not during hot reload

That usually points to HMR graph invalidation rather than a stable production failure. Import-time side effects are especially vulnerable here. Explicit runtime invocation fixes this class of bug more reliably than trying to force the IIFE pattern to survive HMR.

Accessing DOM or window during server rendering

If your IIFE contains browser globals, always guard them:

if (typeof window !== 'undefined') {
  // browser-only code
}

However, a guard alone does not solve timing issues. It only prevents server crashes.

Tree-shaking removes code that appears unused

If the module exports nothing meaningful and only relies on side effects, bundlers may optimize aggressively. Converting the behavior into an explicit function call makes intent clearer and bundling more predictable.

FAQ

1. Is this a JavaScript IIFE bug or a Next.js/Turbopack behavior difference?

It is almost always a runtime and bundling behavior difference, not a language-level JavaScript problem. The IIFE syntax is valid, but where and when the module executes changes under Next.js 15 with Turbopack.

2. Can I keep using an IIFE if I add use client?

You can, but it is still less robust than moving the logic into useEffect. use client fixes the execution environment, while useEffect fixes both environment and timing.

3. Will this bug affect production builds too?

It can, but many reports appear first in development because Turbopack and HMR make import-time side effects more visible. Even if production seems fine, refactoring away from top-level immediate execution is the safer long-term solution.

If you want to inspect the reproduction, use the project linked in the issue: Next.js 15 Turbopack bug demo repository. For framework-level tracking and updates, monitor the related issue discussion in the appropriate Next.js repository and test fixes against your exact client/server component boundaries.