Chrome Extensions · The Manifest
Every extension has one file that makes everything else possible. Without it, Chrome doesn’t know your extension exists — not its name, not which scripts to load, not what permissions it needs, not even its version. That file is manifest.json. Open one for the first time and it looks like a wall of keys and values, but once you know what each section does, it becomes easy to work with. Let’s break down the parts that matter and how they fit together. (This pairs with our 4-part build series.)
What manifest.json is
The manifest is your extension’s configuration file — its instruction manual. When Chrome loads an extension, this is the very first thing it reads, and from it Chrome learns the name, the version, which scripts to run, what permissions are needed, which icons to show, and which pages the extension can touch. Without a manifest there is no extension. (The name comes from shipping: a manifest lists everything inside a shipment — yours lists everything that belongs to your extension and how Chrome should use it.)
manifest.json at the top level of your project folder, alongside popup.html, your scripts and your icons/ folder — never inside a subfolder.A minimal manifest
Here’s a complete, valid Manifest V3 file. It’s short, but it already tells Chrome quite a lot:
{
"manifest_version": 3,
"name": "My First Extension",
"version": "1.0",
"description": "My first Chrome extension.",
"action": {
"default_popup": "popup.html"
},
"permissions": ["storage"]
}The keys you’ll actually use
Most manifests are built from the same handful of keys. Here’s what each one does:
| Key | What it declares |
|---|---|
manifest_version | Which platform version — always 3 for new extensions |
name | The name users see in Chrome |
version | Your release number — bump it every update |
description | A short line explaining what it does |
action | What happens when the icon is clicked (usually a popup) |
permissions | Which Chrome APIs you’re allowed to use |
host_permissions | Which websites you’re allowed to touch |
content_scripts | Which JS/CSS to auto-inject, and on which pages |
background | Your service worker for background work |
icons | Icon files at each size Chrome needs |
web_accessible_resources | Extension files that pages are allowed to load |
options_page | A settings page for your extension |
A few of these are worth a closer look.
manifest_version, name, version, description
Always "manifest_version": 3 — MV2 is deprecated, so if a tutorial uses it, find a newer one. The name should tell users what it does at a glance (“Color Picker Pro”), the version (e.g. "1.2.0") is how Chrome decides whether to push an update — so bump it every release — and the description is a short, informative one-liner.
action
Defines what clicking the toolbar icon does. Point it at your popup and Chrome opens that page:
"action": {
"default_popup": "popup.html"
}permissions & host_permissions
These are two separate lists. permissions unlocks Chrome APIs (storage, activeTab, tabs, scripting, notifications, alarms…), while host_permissions declares which sites you can interact with:
"host_permissions": ["https://*.example.com/*"]Request the minimum of both — it’s the difference between an extension people trust and one they bounce off. (Full detail in our permissions guide.)
content_scripts & background
content_scripts auto-injects JS/CSS into pages that match your pattern; background registers the MV3 service worker that only runs when needed:
"content_scripts": [
{ "matches": ["https://*/*"], "js": ["content.js"] }
],
"background": {
"service_worker": "background.js"
}(These three — popup, content script, service worker — are the extension’s moving parts; see popup vs content vs background.)
icons
Provide every size so your extension stays crisp wherever Chrome shows it — toolbar, extensions page, store:
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
}How Chrome uses the manifest
Every time Chrome starts — or you reload the extension — it reads the manifest first, then works down a predictable list:
1. Validate the file
2. Load permissions
3. Register the service worker
4. Set up the popup
5. Register content scripts
6. Load icons
7. Make the extension availableIf the manifest has an error anywhere in that sequence, the extension may fail to load entirely — which is why a broken extension is so often a broken manifest.
Common beginner mistakes
A missing (or trailing) comma
JSON is strict about punctuation. One missing comma can stop the whole extension loading.
Invalid JSON
Unlike JavaScript, JSON allows no comments, no trailing commas, and no single quotes — only double-quoted keys and values. When Chrome reports a manifest error, run the file through a JSON validator.
Wrong file paths
If a popup, icon or script path doesn’t match your actual folder structure, Chrome can’t find the file. Double-check every filename and location.
Missing permissions
Many APIs need a matching permission. If code suddenly stops working after you add an API, check the manifest before assuming the code is broken.
Following Manifest V2 tutorials
Plenty of older posts and videos still teach MV2. Always confirm your source uses Manifest V3.
Best practices
• Keep the manifest tidy and organised
• Request only the permissions you actually use
• Use clear, incrementing version numbers
• Keep the description current as the extension grows
• Remove permissions and settings you've stopped using
• Validate the JSON whenever Chrome reports an errorA clean manifest is easier to maintain — and inspires more confidence during Chrome Web Store review.
Final thoughts
The manifest is the foundation of every extension. It looks like a simple config file, but it controls almost everything about how your extension behaves — name, icons, permissions, popup, service worker and content scripts. Understand each section and troubleshooting gets easier and your extensions get more reliable.
You’ll come back to this file constantly: nearly every new feature means editing the manifest — a new permission, another script, an extra resource. The better you know it now, the smoother everything downstream will be.
Ready to build around it? Our 4-part series takes you from an empty folder to a published extension. Studio Grid makes Chrome extensions for designers and developers.


