Docs
Blog
Docs
Blog
🛣️

Predictable Path Resolution

Warning: This feature is a work in progress and may be incomplete or subject to change. If you see an error or something that could be improved, please make a pull-request. The link that documents this feature can be found at the bottom of the page.

In Extension.js, file paths defined in the manifest.json are automatically processed and compiled into the appropriate output paths. Whether you’re dealing with JavaScript, HTML, or static assets like images, understanding how these paths are resolved is key to ensuring that you know how to reference them correctly in your extension.

How Does It Work?

Every file path defined in the manifest.json (such as for scripts, icons, and HTML pages) is compiled and output based on the field where it's declared. Below is an overview of common manifest fields and their corresponding output paths.

Assuming the target browser is Chrome:

Manifest Field Input Path Output Path
action.default_popup /src/popup.html /pages/popup.html
background.page /src/background.html /pages/background.html
background.service_worker /src/background.js /scripts/background.js
browser_action.default_popup /src/browser_action.html /pages/browser_action.html
chrome_url_overrides.bookmarks /src/bookmarks.html /pages/bookmarks.html
chrome_url_overrides.history /src/history.html /pages/history.html
chrome_url_overrides.newtab /src/newtab.html /pages/newtab.html
content_scripts.js /src/content_script.js /scripts/content_script.js
content_scripts.css /src/content_style.css /pages/content_style.css
declarative_net_request.rule_resources /src/rules.json /pages/rules.json
devtools_page /src/devtools.html /pages/devtools.html
icons /src/icons/icon.png /public/icons/icon.png
options_ui.page /src/options.html /pages/options.html
page_action.default_popup /src/page_action.html /pages/page_action.html
sandbox.pages /src/sandbox.html /pages/sandbox.html
sidepanel /src/sidepanel.html /pages/sidepanel.html
sidebar_action.default_panel /src/sidebar_panel.html /pages/sidebar_panel.html
storage.managed_schema /src/storage_schema.json /pages/storage_schema.json
theme_icons /src/theme_icons/icon.svg /public/theme_icons/icon.svg
user_scripts.api_script /src/user_script.js /scripts/user_script.js
web_accessible_resources /src/resources/* /public/resources/*

Each file will be compiled and placed in the dist/<browser> folder, where <browser> refers to the target browser (e.g., chrome, firefox, edge).

Referencing Output Files

For browser APIs like chrome.runtime.getURL(), assets must be referenced using absolute paths. This ensures that the browser can correctly resolve the files during runtime:

const iconUrl = chrome.runtime.getURL('/icons/icon.png');
console.log(iconUrl);
 Output: chrome-extension:<extension-id>/icons/icon.png

Without using absolute paths for browser APIs, assets may not load correctly in the extension context.

Output Path of the Entire Extension

When your extension is built, the final output folder will be located at dist/<browser>, where <browser> corresponds to the target browser. All compiled files—scripts, stylesheets, HTML, icons, and other assets—will be placed in this folder.

Example Output Structure

Copy code
dist/
├── chrome/
│   ├── background.js
│   ├── content.js
│   ├── popup.html
│   └── icons/
│       └── icon.png
└── firefox/
    ├── background.js
    ├── content.js
    ├── popup.html
    └── icons/
        └── icon.png

The dist/ folder contains separate subfolders for each supported browser. For example, dist/chrome contains files specific to Chrome, while dist/firefox contains files for Firefox. This ensures cross-browser compatibility, allowing you to manage and test your extension in different environments.

Build Artifacts

After the build process, Extension.js will create a zip file containing all the necessary assets for distribution. The default format for the build artifact is name-version.zip.

Example Build Artifacts

  • my-extension-1.0.0.zip for Chrome
  • my-extension-1.0.0.xpi for Firefox (compatible with .xpi packaging)
  • my-extension-1.0.0.zip for Edge

These zip files are ready for submission to the respective browser's extension store, ensuring that all assets, scripts, and manifest fields are correctly included.

Handling Files Outside the Manifest Scope

Extension.js allows for handling files outside the manifest.json by using special folders like the /pages, /scripts, and /public folder. These folders allow you to manage assets and HTML files that are not directly referenced in the manifest but still need to be processed during the build. Learn more about Special Folders.

Pages

The /pages folder contains HTML files that can be hot-reloaded during development. These files are treated as separate pages that can be dynamically updated without requiring a full extension reload. This folder is useful for managing additional HTML pages that are not declared in the manifest.

The output path for HTML files in the /pages folder is dist/<browser>/pages/<filename>.html.

Scripts

The /scripts folder contains JavaScript files that can be hot-reloaded during development. These files are treated as separate scripts that can be dynamically updated without requiring a full extension reload. This folder is useful for managing additional scripts that are not declared in the manifest.

The output path for JavaScript files in the /scripts folder is dist/<browser>/scripts/<filename>.js.

Public

The /public folder contains static assets like images, stylesheets, and other files that need to be processed during the build. This folder is useful for managing assets that are not directly referenced in the manifest but are required for the extension to function correctly.

The output path for files in the /public folder is the project root directory: dist/<browser>/<filename>.<ext>.

Best Practices

  • Use absolute paths when referencing assets in the manifest.json to ensure correct resolution during runtime.
  • Organize your files into special folders like /pages, /scripts, and /public to manage assets and scripts that are not directly referenced in the manifest.

Next Steps