Skip to main content
Ship extension behavior across background, content scripts, and UI pages with one JavaScript/TypeScript pipeline. Extension.js collects script entrypoints from manifest.json, HTML pages, and special folders. It compiles them with the default SWC (Speedy Web Compiler)-based setup.

Template examples

javascript

javascript template screenshot Vanilla JavaScript extension with a sidebar panel and a content script.
Repository: extension-js/templates/javascript

content

content template screenshot Vanilla JavaScript content script injected into web pages.
Repository: extension-js/templates/content

JavaScript capabilities

Supported script entrypoints

Sample script declaration in manifest.json

Example script declaration in manifest.json:

Development behavior

  • Content scripts: Extension.js injects hot module replacement (HMR)/remount flow for fast updates.
  • Extension pages: Page scripts follow page HMR behavior.
  • Background/service worker: Script updates can trigger a hard extension reload depending on the change type.
  • Entrypoint list changes: When a manifest edit adds, removes, or renames a script entry, a running extension dev session restarts its compiler and reloads the extension. You do not restart the command. From the release after 4.1.41, the session also restarts when a script moves to another manifest key, such as the same file moved from background.scripts to background.service_worker.

Script locations and conventions

  • Use scripts/ at project root for script-centric extension entries.
  • Use pages/ for HTML entrypoints with their own scripts.
  • Keep manifest-referenced paths stable; avoid moving entry files without updating manifest.

Transform and bundling defaults

  • SWC is the default transformer for JS/TS/JSX/TSX.
  • A Chromium build compiles for chrome >= 100, or for the minimum_chrome_version that the manifest sets.
  • From the release after 4.2.0, a Firefox build compiles for firefox >= 98, or for the major version of the Gecko strict_min_version that the manifest sets. Earlier releases compiled a Firefox build with no strict_min_version for chrome >= 100.
  • From the release after 4.2.0, a Safari build compiles for safari >= 15.4. It reads no version from the manifest, because the Xcode project holds that floor.
  • The CSS minimizer of a production build uses the same targets as the scripts.
  • Extension.js uses browser-first package.json field resolution (browser, module, main).
  • Extension.js emits entries predictably and does not split code into separate output files by default.
  • Path resolution rewrites static extension-path literals in supported APIs.

Dynamic import caveats

  • Content-script dynamic import has runtime constraints; Extension.js uses loader fallbacks where possible.
  • The platform does not allow import() or a late importScripts in a service worker. Up to 4.1.41, a lazy import in a Chromium service worker failed at runtime. From the release after 4.1.41, the build bundles it into the worker file, and the module still runs only when first imported. See Lazy loading.

Best practices

  • Keep entry scripts thin and move feature logic into shared modules.
  • Prefer static import paths for extension APIs so path resolution can normalize them safely.
  • Avoid unnecessary dynamic import in content scripts and service workers.
  • Treat manifest script list edits as structural changes in development workflows.

Next steps