manifest.json as the source of truth for entrypoints, assets, and browser-specific behavior.
Extension.js compiles your manifest and filters browser-prefixed fields. It rewrites runtime paths, validates referenced files, and produces a ready-to-load manifest for each target browser.
Manifest capabilities
Where Extension.js reads the manifest
src/manifest.json(preferred when present)manifest.jsonat project root
public/manifest.json as the source manifest.
A manifest.json under public/ fails the build with manifest.json must not be placed under public/. Move it to src/manifest.json or the project root, so a copied static asset never overwrites the manifest that Extension.js generates.
From the release after 4.1.41, the manifest can carry // comments, as Chromium and Firefox allow for an unpacked extension. The same holds for _locales/*/messages.json. The built files carry no comments, because the stores refuse them.
- Chromium also reads
/* */block comments. Firefox does not, so a Firefox build stops and names the line. - Neither browser reads a trailing comma, so the build refuses one for every target.
What Extension.js does with it
During dev/build, the manifest pipeline:- Emits the manifest asset from your source file.
- Filters browser-prefixed keys for the active browser target.
- Applies manifest overrides/path normalization for extension outputs.
- Validates referenced files (HTML/scripts/CSS/icons/JSON) and fails early when missing.
One manifest, multiple browsers
Browser-prefixed keys let you keep one manifest file while still targeting browser-specific behavior:chromium:*for every Chromium-family browser,chrome:*andedge:*for one browser eachfirefox:*,gecko:*
chromium:keybackground.firefox:scriptsbackground.chromium:service_worker
Supported manifest fields
Common entrypoint-related fields include:Permissions design
The manifest is also where your extension declares what it can do. Extension.js compiles the manifest, but you still need good permission design.- Keep
permissionssmall and intentional. - Keep
host_permissionsas narrow as the feature allows. - Move non-core capabilities into
optional_permissionsoroptional_host_permissionswhere possible. - Review permission scope whenever content-script matches or background capabilities change.
Output behavior
Extension.js rewrites manifest paths to predictable output locations when needed. Two important examples:background.service_workerbecomesbackground/service_worker.jsside_panel.default_pathbecomessidebar/index.htmlpage_action.default_popupbecomespage_action/index.html, its own page beside the toolbar popup, on Firefox (any manifest version) and on Chromium MV2. Whenpage_actionandaction(orbrowser_action) name the same file, both keys shareaction/index.html. Chromium MV3 has no page action surface, so the build dropspage_actionfrom that manifest with a warning and emits no page for it.
content_scripts/content-0.jscontent_scripts/content-0.css
key in dist/edge, so the unpacked extension ID stays the same. Only the Edge package that --zip writes leaves key out, because Edge Add-ons refuses a package that carries it, and the build prints one warning saying so. See Browser-specific manifest fields.
Manifest V2 builds fold host permissions and flatten the CSP
From 4.1.18, every build withmanifest_version: 2 reshapes two Manifest V3 keys, on every browser target. Your source manifest stays as you wrote it.
host_permissions folds into permissions, and optional_host_permissions folds into optional_permissions. Each list is deduplicated, and the two MV3 keys are dropped from the emitted manifest. Manifest V2 reads match patterns from permissions, so this is where Firefox expects them.
content_security_policy is emitted as one string, taken from the extension_pages slot of the object form. Manifest V2 has no place for the sandbox slot, so that policy is dropped with a warning:
"permissions": ["storage", "https://example.com/*"] and "content_security_policy": "script-src 'self'", with no host_permissions key.
Development behavior
- When
manifest.jsonchanges, Extension.js recompiles and triggers extension hard reload flow. - 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. - Missing files referenced by manifest fields fail compilation with manifest-focused errors.
Change outcome matrix
What Extension.js repairs for you
Some manifest shapes make Chromium refuse to load the extension outright, with little explanation. Extension.js diagnoses these before the browser launches and auto-repairs the fatal ones. Each repair prints a warning that names the field and the reason. See Manifest refusals for the catalogue of refusal causes and repairs.Legacy path warnings
Development and production builds both warn when the emitted manifest still contains one of these deprecated generated paths:devtools_page/devtools_page.htmloptions_ui/page.htmlbackground/page.htmlbrowser_action/default_popup.htmlpage_action/default_popup.htmlside_panel/default_path.htmlsidebar_action/default_panel.html
ManifestLegacyWarning. Extension.js rewrites these paths to the standardized folders in the next major version.
Best practices
- Keep manifest paths relative to the extension source/output model and use leading
/only when you mean extension output root. - Use browser-prefixed keys instead of maintaining separate manifest files per browser.
- Keep entrypoint changes deliberate; adding/removing manifest scripts often changes reload semantics in dev.
- Validate icons, JSON resources, and content-script assets as part of continuous integration (CI) to catch path regressions early.
- Do not place
manifest.jsonunderpublic/.
Next steps
- Understand update outcomes in dev update behavior.
- Design least-privilege access in Permissions and host permissions.
- Learn how Extension.js handles Browser-specific manifest fields.
- Understand dev update flow in Page reload and hot module replacement (HMR).

