Every browser extension, from the simplest “Hello World” to the most complex productivity tool, starts with a blueprint: the manifest.json file. This JSON-formatted file provides critical metadata and configuration, telling the browser everything it needs to know about your extension, its capabilities, and its permissions.
With the recent shift to Manifest V3, understanding each key and its purpose is more important than ever. Let’s break down the essential components of this powerful file.
1. The Essentials: Required Keys
These are the non-negotiables. Your extension will not load without them.
| Key | Description | Example Value |
manifest_version | Specifies the version of the manifest file format your extension uses. Must be 3 for modern extensions. | 3 |
name | The primary name of your extension displayed in the browser and the Web Store. | "TCMHACK Extension" |
version | The version of your extension, used for updates. Typically follows a MAJOR.MINOR.PATCH format. | "1.0.0" |
2. The Interface & Logic: Core Configuration Keys
These keys define how your extension looks, what scripts it runs in the background, and how it interacts with the user.
| Key | Description | Example Value |
description | A short, plain-text description of your extension, visible in the Web Store. | "A simple extension from TCMHACK." |
icons | Specifies the paths to various icon sizes (16, 32, 48, 128 pixels) used by the browser, OS, and Web Store. | { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" } |
action | Defines the behavior when the user clicks your extension’s icon in the toolbar. This is where you specify a popup or default icon. | { "default_popup": "popup.html", "default_icon": "icons/48.png", "default_title": "Click me!" } |
background | (Manifest V3) Defines the Service Worker script that runs in the background, listening for events and performing tasks without a UI. | { "service_worker": "background.js" } |
content_scripts | Configures JavaScript and/or CSS files to be injected into specific web pages. Used for directly interacting with a page’s DOM. | [{ "matches": [" |
permissions | Requests access to specific browser APIs (e.g., storage, tabs, notifications) or features. Users will be prompted to grant these. | ["storage", "activeTab"] |
host_permissions | Grants your extension access to specific host patterns (URLs) without requiring explicit user consent per API call (unlike permissions). | ["https://*.google.com/*", "http://localhost/*"] |
3. The Advanced Features: Enhancing User Experience & Control
These keys unlock more sophisticated capabilities, offering greater control and a richer user experience.
| Key | Description | Example Value |
options_page | Specifies an HTML page that opens when the user clicks “Options” or “Extension Options” from the context menu. Useful for user settings. | "options.html" |
commands | Defines keyboard shortcuts (commands) that trigger specific actions within your extension. | { "toggle-feature": { "suggested_key": { "default": "Ctrl+Shift+F", "mac": "Command+Shift+F" }, "description": "Toggle main feature" } } |
web_accessible_resources | Declares which resources (images, HTML, JS) inside your extension can be accessed by web pages or other extensions. | [{ "resources": ["image.png", "inject.js"], "matches": [" |
content_security_policy | (Manifest V3) Controls what resources your extension can load (scripts, styles, fonts). Crucial for security; defaults are usually sufficient. | "script-src 'self'; object-src 'self'" |
externally_connectable | Allows external web pages or other extensions to connect to your extension using runtime.connect or runtime.sendMessage. | { "matches": ["https://tcmhack.com/*"] } |
declarative_net_request | (Manifest V3) Enables powerful, high-performance network request blocking or modification without needing JavaScript. | Requires a separate rules.json file. |
Example manifest.json for a Simple Extension
{
"manifest_version": 3,
"name": "TCMHACK Demo Extension",
"version": "1.0.0",
"description": "A simple demo extension for TCMHACK readers.",
"icons": {
"16": "icons/icon16.png",
"48": "icons/icon48.png",
"128": "icons/icon128.png"
},
"action": {
"default_popup": "popup.html",
"default_icon": "icons/icon48.png"
},
"permissions": ["storage"],
"host_permissions": ["https://*.google.com/*"],
"background": {
"service_worker": "background.js"
},
"content_scripts": [
{
"matches": ["https://*.tcmhack.com/*"],
"js": ["content-script.js"],
"css": ["content-style.css"]
}
]
}Conclusion
The manifest.json file is the backbone of your Chrome extension. Understanding each key empowers you to design, secure, and debug your extensions effectively. While it might seem daunting at first, this file provides a clear, declarative way to tell the browser exactly what your extension does.
In our next post, we’ll put some of these keys into action as we dive into Content Scripts, demonstrating how your extension can directly interact with the web pages you visit.
Share this:
Discover more from TCMHACK
Subscribe to get the latest posts sent to your email.
