Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Manifest V3 and Structure

manifest.json Basics

Learn the required and common keys in a Manifest V3 manifest.json: name, version, description, icons, action, background and permissions, with a live validator.

The manifest is the front door of your extension. Before Chrome runs a single line of your code, it reads manifest.json, validates it and builds the extension from what it says. A typo here and the extension will not load, so it pays to know the file well.

This lesson covers the keys you will use in nearly every extension. The next lesson goes through the rest.

The three required keys

A Manifest V3 file must have exactly these:

JSON
{
  "manifest_version": 3,
  "name": "Tab Counter",
  "version": "1.0.0"
}
  • manifest_version is the number 3 (a number, not a string).
  • name is what users see in the store and in chrome://extensions. Up to 75 characters.
  • version is one to four dot-separated integers, each between 0 and 65535: 1, 1.2, 1.2.3, 1.2.3.4. You must raise it every time you upload a new version to the store. 1.0-beta is invalid.

An extension with only these three keys loads fine; it just does nothing.

JSON
{
  "manifest_version": 3,
  "name": "Tab Counter",
  "version": "1.0.0",
  "description": "Shows how many tabs you have open, right on the toolbar icon.",
  "icons": {
    "16": "icons/16.png",
    "48": "icons/48.png",
    "128": "icons/128.png"
  },
  "action": {
    "default_title": "Tab Counter",
    "default_popup": "popup.html"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["tabs"]
}
Key Purpose
description A plain-text summary, up to 132 characters; shown in the store and on the extensions page
icons Images in sizes 16, 32, 48 and 128; used on the extensions page, store and install dialogs
action The toolbar button: its icon, tooltip and popup
background.service_worker The path to your service worker file
permissions API access the extension needs
host_permissions Sites the extension may read and change
content_scripts Scripts to inject into matching pages
options_page or options_ui The settings page

Paths are relative to the folder that contains manifest.json and never start with /.

JSON rules that trip people up

  1. Keys and strings use double quotes.
  2. No comments and no trailing commas.
  3. Numbers are bare (3), strings are quoted ("3"). "manifest_version": "3" is an error.
  4. The file must be saved as UTF-8.
flowchart TD
    A["Chrome reads manifest.json"] --> B{"Valid JSON?"}
    B -- no --> X["Load fails:<br/>Could not load manifest"]
    B -- yes --> C{"Required keys present<br/>and correct types?"}
    C -- no --> X
    C -- yes --> D{"Referenced files exist?"}
    D -- no --> X
    D -- yes --> E["Extension loads"]

Three checks must pass before your extension appears.

Write a validator

You will often wish you could check the manifest quickly. This stand-in validator applies the rules above. Edit the manifest string and run it.

JS Manifest validator (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A quick look at action

action is the toolbar button. If you set default_popup, clicking the icon opens that page. If you leave the popup out, clicking fires chrome.action.onClicked in your service worker instead, which is how an extension runs code on a single click without any UI. You can have one or the other, not both.

JS Popup or click event?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Where to find mistakes

Open chrome://extensions, find your extension and click Errors. A failed load usually names the key in the message, for example Unrecognized manifest key 'browser_action' (V2 leftover) or Invalid value for 'content_scripts[0].matches[0]'. Fix the file, press reload, and repeat.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which three keys are required in every Manifest V3 manifest?

    Chrome requires manifest_version, name and version. Everything else is optional.
  2. 2. Which version string is valid?

    A version is one to four dot-separated integers. Letters and hyphens are not allowed.
  3. 3. What happens when you leave out default_popup in the action key?

    Without a popup the click event goes to your service worker, where you can run any logic.
  4. 4. Is a comment allowed in manifest.json?

    Chrome parses the manifest as JSON, which has no comments. A comment makes the file fail to load.

Summary

  • manifest_version, name and version are mandatory.
  • Add description, icons, action and background for a real extension.
  • Paths are relative to the manifest, with no leading slash.
  • The file is strict JSON: double quotes, no comments, no trailing commas.
  • Reload the extension and read the Errors button after each change.

Next: Manifest Fields Reference