Module aliases and import resolution

An alias maps an import specifier onto a folder in your project. It replaces ../../../lib/badge with @lib/badge. Extension.js supports two ways to declare one. This page is about module specifiers in import statements. For asset paths in manifest.json and in extension API calls, read Predictable path resolution.

Declare aliases in tsconfig.json

Extension.js hands your tsconfig.json to the bundler resolver. Anything that you put in compilerOptions.paths applies to the build:

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@lib/*": ["src/lib/*"]
    }
  }
}

src/content/scripts.js

import { BADGE_TEXT } from "@lib/badge.js";

baseUrl is optional. Without it, write the targets relative to the folder that holds tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@lib/*": ["./src/lib/*"]
    }
  }
}

Extension.js looks for tsconfig.json beside the nearest package.json first, then in the project folder.

This works in JavaScript projects too

A tsconfig.json file is the alias source even when every file that you import is plain JavaScript. You do not have to convert the project to TypeScript, and you do not have to install the typescript package for the alias to resolve.

jsconfig.json is not read

Extension.js does not read jsconfig.json. A paths block in that file has no effect, and the build fails on the alias:

Module not found: Can't resolve '@lib/badge.js'

Rename the file to tsconfig.json to fix it.

Declare aliases in extension.config.js

The config hook receives the full bundler configuration. Add resolve.alias there when you prefer to keep the alias out of tsconfig.json:

extension.config.js

import path from "node:path";

export default {
  config: (config) => {
    config.resolve = config.resolve || {};
    config.resolve.alias = {
      ...(config.resolve.alias || {}),
      "@lib": path.resolve(process.cwd(), "src/lib"),
    };
    return config;
  },
};

The hook runs for dev and for build, so one declaration covers both. Read Rspack configuration for the rest of the hook.

Aliases that Extension.js sets for you

Extension.js defines no folder aliases of its own. There is no built-in @/, ~/, or src/ prefix. Every alias that the toolchain injects pins a package to one copy:

Area	Aliased specifiers
Polyfill	`webextension-polyfill`
React	`react`, `react-dom`, `react-dom/client`, the JSX runtimes
Preact	`preact`, plus the `react` and `react-dom` names mapped onto Preact
Vue	`vue`, `@vue/runtime-dom`, `@vue/runtime-core`, `@vue/shared`
Svelte	`svelte`, `svelte/store`
WebAssembly packages	`@ffmpeg/core`, `@imagemagick/magick-wasm`, `tesseract-wasm` assets

Framework aliases lose to yours. Extension.js merges your resolve.alias last, so an alias that names react in the config hook wins. One key is the exception. The polyfill alias webextension-polyfill$ is applied after yours, so an alias on that exact specifier does not take effect.

File extensions in specifiers

Extension.js resolves these extensions without you naming them: .js, .cjs, .mjs, .jsx, .ts, .mts, .tsx, .json, .svelte. It also maps output-style specifiers back onto sources. An import of ./badge.js resolves against badge.ts or badge.tsx when the JavaScript file does not exist.

Best practices

Keep one alias source. Two declarations of the same prefix are hard to trace.
Prefer tsconfig.json when your editor should follow the alias too. The config hook is invisible to editors.
Point an alias at a folder inside the project. An alias that reaches outside the root breaks the packaged output.

Next steps

Learn how asset paths resolve in Predictable path resolution.
Change bundler settings in Rspack configuration.
Read about TypeScript support.

Introduction

Browser extension fundamentals

Getting started

Compare and migrate

Commands reference

Features

Browsers

Languages and frameworks

Integrations

Workflows

Machine contracts

Publish to the stores

Debugging

Implementation guide

Community

Module aliases and import resolution

Declare aliases in tsconfig.json

This works in JavaScript projects too

jsconfig.json is not read

Declare aliases in extension.config.js

Aliases that Extension.js sets for you

File extensions in specifiers

Best practices

Next steps

​Declare aliases in tsconfig.json

​This works in JavaScript projects too

​jsconfig.json is not read

​Declare aliases in extension.config.js

​Aliases that Extension.js sets for you

​File extensions in specifiers

​Best practices

​Next steps

Declare aliases in tsconfig.json

This works in JavaScript projects too

jsconfig.json is not read

Declare aliases in extension.config.js

Aliases that Extension.js sets for you

File extensions in specifiers

Best practices

Next steps