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.*).
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://andhttps://URLsdata:URLschrome://URLsmoz-extension://URLs- Glob patterns (
*,?,{},[]) - Non-static/dynamic expressions that the build cannot safely resolve
Manifest output examples
Assuming target browserchrome:
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 asindex.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:
/ 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 likechrome.runtime.getURL(), prefer stable, output-root paths:
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, nestedsrc/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/andscripts/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/, andpublic/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
devas they usually indicate path mismatches before packaging.
Next steps
- Learn more about Special folders.
- Learn more about web-accessible resources.

