ECMAScript modules in extensions

Author extension code with modern import/export syntax across all extension contexts. Extension.js supports ECMAScript Modules (ESM) in background scripts, content scripts, and extension pages. It uses the default Rspack pipeline for module resolution.

When ESM is a good fit

You want consistent module syntax across extension and web code.
You are sharing code with modern ESM-first packages.
You need cleaner tree-shaking (automatic removal of unused code) and explicit dependency boundaries.

Template examples

`new`

Start a new-tab extension with modern module syntax and minimal setup.

npx extension@latest create my-extension --template=new

pnpx extension@latest create my-extension --template=new

yarn dlx extension@latest create my-extension --template=new

bunx extension@latest create my-extension --template=new

deno run -A npm:extension@latest create my-extension --template=new

Repository: extension-js/examples/new

`content`

Inject script logic into page content while keeping ESM-style authoring.

npx extension@latest create my-extension --template=content

pnpx extension@latest create my-extension --template=content

yarn dlx extension@latest create my-extension --template=content

bunx extension@latest create my-extension --template=content

deno run -A npm:extension@latest create my-extension --template=content

Repository: extension-js/examples/content

Usage with an existing extension

You can use ESM syntax directly in extension source files (.js, .mjs, .ts, .tsx, etc.) without custom bundler setup. If your Node.js project configuration files should also run as ESM, set "type": "module" in package.json. This applies to custom scripts and configuration conventions:

{
  "name": "my-extension",
  "version": "1.0",
  "description": "My Extension Example",
  "type": "module",
  "devDependencies": {
    "extension": "latest"
  },
  "scripts": {
    "dev": "extension dev",
    "start": "extension start",
    "build": "extension build"
  }
}

Manifest and service worker notes

For Manifest V3 background workers:

Set background.type to "module" when you want native ES module loading in the service worker.
Without module worker type, Extension.js uses classic worker loading (bundled scripts without native module syntax).

{
  "background": {
    "service_worker": "src/background.ts",
    "type": "module"
  }
}

ESM vs CommonJS reminders

When writing ESM modules:

Include file extensions in relative imports

// my-file.mjs
import React from 'react'

// local imports
- import myImport from './myImport'
+ import myImport from './myImport.js'

Interoperability with non-ESM modules can differ

When importing CommonJS packages from ESM, follow the compatibility guidance each package provides.

CommonJS globals are not available in strict ESM contexts

Avoid relying on require, module.exports, __filename, and __dirname inside ESM modules.

Handling environment variables in ECMAScript modules

Extension.js supports both:

process.env.EXTENSION_PUBLIC_*
import.meta.env.EXTENSION_PUBLIC_*

Use EXTENSION_PUBLIC_ for variables you want available in extension code.

// example.mjs

console.log(import.meta.env.EXTENSION_PUBLIC_API_KEY);
console.log(process.env.EXTENSION_PUBLIC_API_KEY);

Do imports need mandatory file extensions?

Node.js requires explicit file extensions in ESM import specifiers (import "./util.js", never import "./util"). That rule applies to code Node runs directly, and it confuses people coming to extensions from server code. In Extension.js the bundler resolves imports, not Node, so both styles work in extension code:

import { parse } from "./util"; // resolved by the bundler
import { parse } from "./util.js"; // also fine

Two places the Node rule still matters:

Scripts your package.json runs with Node directly (build helpers, codegen): extensions are mandatory there.
.mjs files shared between Node tooling and extension code: write extensions so both resolvers accept them.

Next steps

Learn more about TypeScript.
Explore how Extension.js handles CSS modules.

Video walkthrough

TypeScript for browser extensions React for browser extensions

⌘I

​When ESM is a good fit

​Template examples

​new

​content

​Usage with an existing extension

​Manifest and service worker notes

​ESM vs CommonJS reminders

​Include file extensions in relative imports

​Interoperability with non-ESM modules can differ

​CommonJS globals are not available in strict ESM contexts

​Handling environment variables in ECMAScript modules

​Do imports need mandatory file extensions?

​Next steps

​Video walkthrough