manifest.json, HTML pages, and special folders. It compiles them with the default SWC (Speedy Web Compiler)-based setup.
Template examples
javascript

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 devsession 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 frombackground.scriptstobackground.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 theminimum_chrome_versionthat the manifest sets. - From the release after 4.2.0, a Firefox build compiles for
firefox >= 98, or for the major version of the Geckostrict_min_versionthat the manifest sets. Earlier releases compiled a Firefox build with nostrict_min_versionforchrome >= 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.jsonfield 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 lateimportScriptsin 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
- Understand update outcomes in dev update behavior.
- Learn how to structure files with Special folders.
- Continue with background scripts and service workers.

