Documentation Index
Fetch the complete documentation index at: https://extension.js.org/llms.txt
Use this file to discover all available pages before exploring further.
Keep extension builds predictable by treating 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
| Capability | What it gives you |
|---|
| Browser-specific field filtering | Keep one manifest file while emitting target-specific output |
| Path normalization | Resolve runtime-safe output paths automatically |
| Reference validation | Fail early when HTML/script/CSS/JSON/icon files are missing |
| Targeted outputs | Generate manifest artifacts per browser target in dist/<browser> |
Where Extension.js reads the manifest
src/manifest.json (preferred when present)manifest.json at project root
Extension.js does not use public/manifest.json as the source manifest.
When a project has a package.json, Extension.js ignores public/manifest.json. This prevents a copied static asset from overwriting the manifest that Extension.js generates.
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:*, chrome:*, edge:*firefox:*, gecko:*
These prefixes can apply to top-level keys and nested manifest fields.
Examples:
chromium:keybackground.firefox:scriptsbackground.chromium:service_worker
Supported manifest fields
Common entrypoint-related fields include:
| Manifest field | File type expected |
|---|
action.default_popup | .html |
background.page | .html |
background.service_worker | .js, .jsx, .ts, .tsx, .mjs |
browser_action.default_popup | .html |
chrome_url_overrides.bookmarks | .html |
chrome_url_overrides.history | .html |
chrome_url_overrides.newtab | .html |
content_scripts.js | .js, .jsx, .ts, .tsx, .mjs |
content_scripts.css | .css, .scss, .sass, .less |
declarative_net_request.rule_resources | .json |
devtools_page | .html |
icons | .png, .jpg, …Other image formats |
options_ui.page | .html |
options_page | .html |
page_action.default_popup | .html |
sandbox.pages | .html |
side_panel.default_path | .html |
sidebar_action.default_panel | .html |
storage.managed_schema | .json |
theme_icons | .png, .jpg, …Other image formats |
user_scripts.api_script | .js, .jsx, .ts, .tsx, .mjs |
web_accessible_resources | .png, .jpg, .css, .js |
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
permissions small and intentional.
- Keep
host_permissions as narrow as the feature allows.
- Move non-core capabilities into
optional_permissions or optional_host_permissions where possible.
- Review permission scope whenever content-script matches or background capabilities change.
For permission strategy, see Permissions and host permissions.
Output behavior
Extension.js rewrites manifest paths to predictable output locations when needed. Two important examples:
background.service_worker becomes background/service_worker.jsside_panel.default_path becomes sidebar/index.html
Extension.js also normalizes content scripts by manifest entry index:
content_scripts/content-0.jscontent_scripts/content-0.css
Those emitted paths are what the browser actually loads. Use source paths in authoring, then let Extension.js rewrite them for output.
Development behavior
- When
manifest.json changes, Extension.js recompiles and triggers extension hard reload flow.
- If manifest entrypoint structure changes (for example, script list changes), Extension.js may require a dev server restart.
- Missing files referenced by manifest fields fail compilation with manifest-focused errors.
Change outcome matrix
| Manifest change type | Typical outcome |
|---|
| Update non-structural values (for example, descriptions/permissions metadata) | Hard reload flow |
| Update asset path values that still resolve cleanly | Recompile + hard reload flow |
| Add/remove script or page entrypoints in manifest | Restart required |
| Introduce invalid/missing referenced files | Build error (fix first, then rerun) |
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.json under public/.
Next steps
