Lazy loading heavy libraries in extensions

Manifest V3 service workers cold-start often: the browser kills them after ~30 seconds of inactivity and restarts them on the next event. Every kilobyte you import at the top of the worker is parsed again on every wake-up. A bundled parser, wasm runtime, or AI SDK in the worker entry makes every alarm, message, and click pay that cost.

Where dynamic `import()` works

The platform rules, before any bundler enters the picture:

Context	Dynamic `import()` at runtime
Service worker (background)	No, the spec disallows it
Extension pages (popup, options, new tab, side panel)	Yes
Offscreen documents	Yes
Content scripts	Yes, with one extra step

The service worker restriction is the one that surprises people: dynamic import() is unavailable inside service workers at the platform level, in any browser. Static import statements at the top of the worker are fine (Extension.js bundles them), but you cannot defer a chunk load until an event fires.

Pattern 1: split by surface, not by chunk

The service worker should orchestrate, not compute. Keep its static imports to glue code (routing messages, registering listeners) and move anything heavy to a surface where lazy loading works:

UI-adjacent work belongs in the page that needs it. A popup that formats code imports the formatter in the popup, not the worker.
Background-only heavy work (parsing, encoding, inference) belongs in an offscreen document, created on demand and closed when done. The worker stays a thin message router.

background.ts

chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
  if (message.type === "parse-feed") {
    ensureOffscreen()
      .then(() =>
        chrome.runtime.sendMessage({ target: "offscreen", ...message }),
      )
      .then(sendResponse);
    return true;
  }
});

The offscreen page can then import() the heavy library the first time it is asked, and the cost is paid once per document lifetime instead of once per worker wake-up.

Pattern 2: lazy import inside extension pages

Inside any extension page, plain dynamic import works and the bundler splits the chunk automatically:

popup.ts

button.addEventListener("click", async () => {
  const { highlight } = await import("./heavy/highlighter");
  output.innerHTML = highlight(input.value);
});

Nothing extension-specific here: the chunk is emitted into your build output and loads from the extension’s own origin.

Pattern 3: lazy import in content scripts

Content scripts execute in the page, so their lazily loaded chunks must be fetchable by that page. Two steps:

Expose the chunk paths via web_accessible_resources.
Import through chrome.runtime.getURL so the URL resolves to your extension origin:

content.ts

async function loadAnalyzer() {
  const src = chrome.runtime.getURL("content_scripts/analyzer.js");
  return import(src);
}

See web_accessible_resources for the matching manifest block. Without it, the import fails with a network error because the host page cannot fetch extension files that are not explicitly exposed.

What to keep out of the worker entirely

Anything DOM-shaped (DOMParser, canvas, audio): the worker has no DOM at all; use an offscreen document.
Multi-megabyte wasm: instantiate it in an offscreen document or an extra page, and cache results in chrome.storage so restarts are cheap.
One-off tooling (imports, migrations, exports): a dedicated page under pages/ keeps it out of every startup path.

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Publish to the stores

Debugging

Implementation guide

Community

Lazy loading heavy libraries in extensions

Where dynamic `import()` works

Pattern 1: split by surface, not by chunk

Pattern 2: lazy import inside extension pages

Pattern 3: lazy import in content scripts

What to keep out of the worker entirely

See also

​Where dynamic import() works

​Pattern 1: split by surface, not by chunk

​Pattern 2: lazy import inside extension pages

​Pattern 3: lazy import in content scripts

​What to keep out of the worker entirely

​See also

Where dynamic `import()` works

Pattern 1: split by surface, not by chunk

Pattern 2: lazy import inside extension pages

Pattern 3: lazy import in content scripts

What to keep out of the worker entirely

See also