Chrome Extension manifest.json Example (Manifest V3)
A complete, copy-paste manifest.json for Manifest V3, with every field explained line by line.
Every Chrome extension starts with manifest.json. It tells Chrome what your extension is called, what it is allowed to do, and which files run where. Get it wrong and Chrome refuses to load the folder at all.
A complete Manifest V3 example
{ "manifest_version": 3, "name": "Focus Timer", "version": "1.0.0", "description": "Blocks distracting sites and runs a Pomodoro timer.", "action": { "default_popup": "popup.html", "default_icon": { "16": "icons/icon16.png", "32": "icons/icon32.png", "48": "icons/icon48.png", "128": "icons/icon128.png" } }, "background": { "service_worker": "background.js" }, "permissions": ["storage", "alarms"], "host_permissions": ["https://*/*"], "content_scripts": [{ "matches": ["https://*/*"], "js": ["content.js"], "run_at": "document_idle" }], "icons": { "16": "icons/icon16.png", "48": "icons/icon48.png", "128": "icons/icon128.png" } }
Field by field
- manifest_version: must be 3. Manifest V2 extensions are no longer accepted.
- name, version, description: store metadata. version must be dot-separated integers.
- action: the toolbar button — default_popup and default_icon live here.
- background.service_worker: a single JS file, event-driven, no persistent page.
- permissions vs host_permissions: API access vs site access, kept separate in V3.
- content_scripts: files injected into matching pages, with run_at controlling timing.
- icons: the install/Web Store icon set, separate from the toolbar icon.
Common mistakes
- Referencing a file path that does not exist — Chrome fails the whole load.
- Using remote scripts or inline handlers, which Manifest V3 CSP blocks.
- Putting host patterns in permissions instead of host_permissions.
- Shipping SVG icons — Chrome's toolbar requires PNGs.
Frequently asked questions
Is manifest.json required for every Chrome extension?
Yes. It is the only mandatory file and must sit at the root of the extension folder.
What is the minimum valid manifest.json?
Three fields: manifest_version, name and version. Everything else is optional but almost every real extension adds action, background or content_scripts.