Quick answer
A Manifest V3 manifest declares the extension’s identity, entry points, and capabilities. The required platform keys are manifest_version, name, and version; feature keys should follow actual behavior. A toolbar popup does not require a worker, and a worker does not grant website access by itself.
Treat the manifest as a reviewable contract for the installed package. A key naming worker.js means that file must exist at the package root. A host pattern means the product has a reason to interact with those sites. Copying a large starter manifest creates both missing-file failures and permission requests that the feature may never use.
Practical implementation steps
Write identity before capabilities
Use valid JSON and a numeric dotted version such as 1.0.0. Do not put a prerelease suffix in version; a human-readable label belongs in version_name. Keep the description within its manifest limit, and include actual packaged icons before Store publication.
Name the surface and its entry point
action.default_popup opens an extension HTML page. background.service_worker names the single worker entry file; add type: "module" if that entry uses module imports. options_ui.page configures a settings page. None of these should reference your source TypeScript or a local development-server URL.
Distinguish three access declarations
permissions enables named APIs such as storage or scripting. host_permissions grants access to declared website origins for relevant operations. content_scripts.matches controls where a declared content script is injected. These are related but not interchangeable: a host permission does not itself schedule a script, and a storage permission does not grant DOM access.
Choose automatic versus user-invoked access
For a one-off page inspection, activeTab plus scripting often matches the interaction. For an automatic enhancement on one site, declare a narrowly matched content script. Optional host permissions can defer access until a user enables a corresponding feature. File URL access and protected browser pages need separate consideration; an expansive match pattern does not bypass browser restrictions.
Review the output manifest
Load the output directory and use Chrome’s error message to locate malformed JSON, unsupported values, and missing paths. Check the ZIP root too: an extra containing folder may leave manifest.json below the root expected by the upload. Keep an explanation beside each capability in your repository documentation rather than putting invalid comments into JSON.
Implementation example
This example is a user-invoked inspection popup with saved preferences. Remove storage and options_ui if the product has no preferences; remove background if there are no worker events. All named files must be included.
{
"manifest_version": 3,
"name": "Focused page inspector",
"description": "Inspect the current page when requested.",
"version": "1.0.0",
"action": { "default_popup": "popup.html" },
"background": { "service_worker": "worker.js", "type": "module" },
"options_ui": { "page": "options.html", "open_in_tab": true },
"permissions": ["activeTab", "scripting", "storage"],
"icons": { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" }
}
An automatic script has a different declaration. This matches HTTPS pages on a specific host and its subdomains; document_idle is appropriate for a DOM task that does not need to intercept initial parsing. Do not add it to the previous example unless automatic behavior is intended.
{
"content_scripts": [{
"matches": ["https://*.example.com/*"],
"js": ["content.js"],
"run_at": "document_idle"
}]
}
Tradeoffs and alternatives
Generating a manifest can keep hashed entry references accurate, but the generated result must remain readable and validated. Separate development and production configuration when development needs differ; compare permissions before release to catch accidental expansion.
Use minimum_chrome_version when a required API needs a browser floor. Choose it from the API’s documented availability, not from your machine’s version. Setting it unnecessarily high excludes users; omitting a necessary floor leaves unsupported installations. Font Picker illustrates a narrow user-facing purpose, but its product page is not evidence that every inspector needs the example’s permissions.
Common mistakes
- Leaving JSON comments or trailing commas in the final file.
- Using
background.scriptsfrom Manifest V2 instead ofservice_worker. - Listing
tabsor all hosts without a corresponding data-access requirement. - Expecting
web_accessible_resourcesto enable scripting; it exposes selected assets to specified web origins. - Assuming localized manifest placeholders work without
default_localeand matching message files.
Production checklist
- The manifest parses as JSON and every path exists in the final root.
- Each permission and host pattern has a specific feature reason.
- Module-worker configuration matches the emitted JavaScript.
- Version and compatibility floor satisfy their documented formats.
- Store description, icons, and privacy disclosures agree with package behavior.
- The uploaded ZIP matches the artifact loaded for review.
FAQ
Does a popup click also fire action.onClicked?
No. When a popup is configured, the action opens it. Put its user interaction in the popup or choose an action without a popup.
Are optional permissions a substitute for explaining access?
No. They defer a request but still require a purpose and a recovery path when access is refused.
What should I check after editing the manifest?
Reload the extension, inspect installation errors, and exercise the changed capability. A JSON parser proves syntax; it does not prove that permissions match the intended runtime operation.
Primary sources
Related guides and examples
Need this implemented in a real product?
Browser tools with a clear purpose, focused permissions, and a maintainable Manifest V3 architecture.