IHOR.DEVKNOWLEDGE_BASE
MENU

~/blog / Extensions / how-to-write-a-manifest-v3-manifest-json-file.md

// pillar guide · 4 min read

How to Write a Manifest V3 manifest.json File

Choose Manifest V3 keys from actual behavior: action and worker entry points, API versus host permissions, content-script matches, and verifiable package paths.

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.scripts from Manifest V2 instead of service_worker.
  • Listing tabs or all hosts without a corresponding data-access requirement.
  • Expecting web_accessible_resources to enable scripting; it exposes selected assets to specified web origins.
  • Assuming localized manifest placeholders work without default_locale and 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

Ihor Kharchyshyn

Independent full-stack product engineer writing source-backed implementation guides for browser extensions and modern web products.

Need this implemented in a real product?

Browser tools with a clear purpose, focused permissions, and a maintainable Manifest V3 architecture.