Skip to main content
Write paths the way you naturally author them, and let Extension.js normalize them to runtime-safe output paths. Keep runtime paths working when you move files, rename entries, or change browser targets. Extension.js rewrites supported paths across manifest fields and extension API usage. Compiled assets resolve correctly inside dist/<browser>.

How it works

Path resolution runs in two places:
  • Manifest compilation pipeline: resolves manifest-declared paths to emitted assets.
  • Path-resolve plugin for JS/TS: rewrites static path literals passed to supported extension APIs (for example, runtime.getURL, tabs.update, scripting.*, action.*, sidePanel.*).
Both passes anchor on the project root, the directory that contains your package.json. That is why pages/, scripts/, and public/ inputs resolve only from that directory, never from src/, even when src/manifest.json defines the extension. See the root rule in Special folders.

Supported input styles

Extension.js normalizes common path inputs as follows: Extension mapping for pages/ and scripts/ includes:
  • .ts, .tsx, .js, .jsx → .js
  • .njk, .nunjucks, .html → .html
  • .scss, .sass, .less, .css → .css

Cases Extension.js does not rewrite

To avoid false positives, Extension.js intentionally skips these inputs:
  • http:// and https:// URLs
  • data: URLs
  • chrome:// URLs
  • moz-extension:// URLs
  • Glob patterns (*, ?, {}, [])
  • Non-static/dynamic expressions that the build cannot safely resolve

Manifest output examples

Assuming target browser chrome: Not every manifest field maps to a folder with the same source name. Extension.js bases output paths on the browser-facing extension contract, not on your original authoring path. Extension.js emits all compiled outputs under dist/<browser>.

Relative paths set from a moved page

Each page that the manifest declares ships in a folder named after its surface. A side panel written as index.html ships as sidebar/index.html. The build rewrites the paths in the page’s HTML. It does not rewrite a relative src or href that the page’s script sets, and the browser resolves that path against the new folder:
Start the path with / so that it resolves from the extension root. From the release after 4.1.39, the build prints a Runtime-risk warning when the file exists at the old relative location only. The warning names the page, the path that the page requests, the path that the output holds, and the path to write.

Referencing output files

For browser APIs like chrome.runtime.getURL(), prefer stable, output-root paths:
Output: chrome-extension://<extension-id>/icons/icon.png

Diagnostics and safety checks

The resolver warns you when it cannot resolve a referenced path to a packaged asset (for example, nested src/pages/... or missing public/ files after rewrite).
Extension.js de-duplicates warnings per file transform pass to reduce noise.

Important path rules

  • Leading / means extension output root, not filesystem root.
  • public/... and /public/... normalize to output-root assets.
  • pages/ and scripts/ are special folders with extension mapping rules.
  • Extension.js preserves absolute OS file paths instead of treating them as extension output paths.
  • Extension.js skips dynamic expressions when it cannot safely determine the final packaged path.

Best practices

  • Keep pages/, scripts/, and public/ at project root for predictable rewrites.
  • Use static literals for extension API paths when possible; Extension.js may skip dynamic expressions.
  • Treat /public/... as output-root assets and avoid source-relative assumptions at runtime.
  • Validate warnings during dev as they usually indicate path mismatches before packaging.

Next steps