Opens in a new tab

manifest.json Explained: Understanding the Heart of Your Chrome Extension

ThemanifestOne file describes your whole extension.manifest.json“manifest_version”: 3,“name”: “My Extension”,“action”: { … },“permissions”: [ … ]
The manifest is the heart of every extension.

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.)

It lives in the root. Chrome always expects 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:

KeyWhat it declares
manifest_versionWhich platform version — always 3 for new extensions
nameThe name users see in Chrome
versionYour release number — bump it every update
descriptionA short line explaining what it does
actionWhat happens when the icon is clicked (usually a popup)
permissionsWhich Chrome APIs you’re allowed to use
host_permissionsWhich websites you’re allowed to touch
content_scriptsWhich JS/CSS to auto-inject, and on which pages
backgroundYour service worker for background work
iconsIcon files at each size Chrome needs
web_accessible_resourcesExtension files that pages are allowed to load
options_pageA 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 available

If 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 error

A 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.

Put the manifest to work

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.

Explore Studio Grid tools →

Illustrated portrait of Mark Carranza
Written by Mark Carranza
Founder, Studio Grid
Mark leads the design of every Studio Grid tool, from Studio Colour in the browser to Studio Convert on the Mac.

Related posts

Leave the first comment