Build Your First Chrome Extension (Manifest V3): A Hands-On Tutorial
Build a small, privacy-friendly Chrome extension from scratch: manifest.json, a popup, activeTab, scripting, storage and a keyboard shortcut. No frameworks needed.
The best way to understand extensions, including what the scary permission warnings mean, is to build one. In this tutorial we’ll make Reading Time, a tiny extension that shows how many words are on the current page and how long it takes to read. It’s small enough to finish in half an hour, but it uses the patterns real extensions use: a popup, a script injected into the page, saved settings and a keyboard shortcut.
It also does this with no permission warnings at all at install time. That’s deliberate, and it’s the most valuable habit a new extension developer can pick up.
You need Chrome (or Edge or Brave), a text editor and nothing else: no Node.js, no build step, no framework. Everything here is current Manifest V3 as of November 2026. If you want background on what MV3 is, read Manifest V3 explained first.
What we’re building
- Click the toolbar icon (or press Alt+Shift+R) and a popup shows something like “1,482 words · about 6 min”.
- You can set your own reading speed in words per minute, and it’s remembered across devices if Chrome sync is on.
- The extension can only read a page after you click it. It can’t see your browsing in the background.
Step 1: Create the folder and manifest
Make a new folder called reading-time. Inside it, create manifest.json:
{
"manifest_version": 3,
"name": "Reading Time",
"version": "1.0.0",
"description": "Shows the word count and reading time of the page you're on.",
"action": {
"default_popup": "popup.html",
"default_title": "Reading time"
},
"permissions": ["activeTab", "scripting", "storage"],
"commands": {
"_execute_action": {
"suggested_key": { "default": "Alt+Shift+R" }
}
}
}
What each part does:
manifest_version: 3tells Chrome to use the current extension platform. MV2 extensions no longer run in Chrome.actionis the toolbar button.default_popupis the small page that opens when you click it.permissions:activeTabgrants temporary access to the current tab only after the user invokes the extension, by clicking the icon or using its shortcut. It shows no install warning.scriptinglets us run a function inside that page.storagelets us save the reading-speed setting.
commands→_execute_actionis a special command name that opens the popup with a keyboard shortcut. A shortcut also counts as invoking the extension, soactiveTabapplies.
Notice what’s not there: no host_permissions, no <all_urls>, no tabs. We don’t need them.
Step 2: The popup HTML
Create popup.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<style>
body { font: 14px system-ui, sans-serif; width: 240px; margin: 12px; }
#result { font-size: 16px; font-weight: 600; margin: 4px 0 12px; }
label { display: flex; justify-content: space-between; align-items: center; gap: 8px; }
input { width: 70px; }
</style>
</head>
<body>
<div id="result">Counting…</div>
<label>Words per minute <input id="wpm" type="number" min="100" max="600" step="10" /></label>
<script src="popup.js"></script>
</body>
</html>
The script is loaded from a separate file. MV3’s Content Security Policy blocks inline <script> code in extension pages, so <script>alert(1)</script> inside the HTML simply won’t run. This trips up almost everyone the first time.
Step 3: The popup logic
Create popup.js:
const result = document.getElementById('result');
const wpmInput = document.getElementById('wpm');
// Runs inside the web page, not in the popup.
function countWords() {
const root = document.querySelector('article, main') || document.body;
const text = root.innerText || '';
return text.split(/\s+/).filter(Boolean).length;
}
async function render() {
const { wpm = 230 } = await chrome.storage.sync.get('wpm');
wpmInput.value = wpm;
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
try {
const [{ result: words }] = await chrome.scripting.executeScript({
target: { tabId: tab.id },
func: countWords,
});
const minutes = Math.max(1, Math.round(words / wpm));
result.textContent = `${words.toLocaleString()} words · about ${minutes} min`;
} catch (err) {
// Chrome blocks scripts on chrome:// pages and the Web Store.
result.textContent = "Can't read this page.";
}
}
wpmInput.addEventListener('change', async () => {
const wpm = Math.min(600, Math.max(100, Number(wpmInput.value) || 230));
await chrome.storage.sync.set({ wpm });
render();
});
render();
A few things worth understanding here:
chrome.scripting.executeScript({ func })serializes thecountWordsfunction and runs it in the page. That’s why it can’t use variables from the popup. Anything it needs must be passed withargs. Its return value comes back to the popup.chrome.tabs.queryworks without thetabspermission. We only usetab.id, and we don’t read the URL or title, which would needtabsand trigger the “Read your browsing history” warning.chrome.storage.syncstores small settings and syncs them through the user’s Chrome account. For larger data, usechrome.storage.local.- Every Chrome extension API used here returns a Promise in MV3, so
async/awaitworks everywhere. - Since Chrome 148 you can also write
browser.storage.sync.get(...)instead ofchrome.…. Chrome now supports the standardbrowsernamespace (docs), which makes porting to Firefox easier. This guide keepschrome.*because it works in every Chromium browser people are likely to have.
Step 4: Load it in Chrome
- Open
chrome://extensions. - Turn on Developer mode (top right).
- Click Load unpacked and select your
reading-timefolder. - Click the puzzle-piece icon in the toolbar and pin Reading Time.
- Open any article and click the icon.
If something’s wrong, Chrome shows an Errors button on the extension’s card. For popup bugs, right-click inside the popup and choose Inspect to open DevTools for the popup itself. Your console.log output from popup.js appears there, not in the page’s console.
The same steps work in Edge (edge://extensions) and Brave (brave://extensions).
Step 5: Test the edge cases
Good extensions fail politely. Try these:
chrome://pages and the Chrome Web Store: Chrome doesn’t let extensions script these, so you’ll see “Can’t read this page.” That’s thecatchblock doing its job.- A PDF: Chrome’s PDF viewer isn’t a normal page, so it also lands in the
catch. - A huge page:
innerTextforces layout, which can be slow on very large pages. For a production extension you might count words fromtextContentinstead, accepting slightly less accurate results. - Reading speed: change the number, close the popup, reopen it. The value should persist.
Step 6: Change the shortcut
Open chrome://extensions/shortcuts. You’ll see Reading Time with Alt+Shift+R. Users can change or remove it here. Suggested shortcuts are only suggestions, and Chrome won’t assign one that clashes with an existing browser shortcut.
Step 7 (optional): Add a right-click menu with a service worker
So far there’s no background code at all, which is ideal. If you want a context-menu item, you need a service worker. Add this to manifest.json:
"background": { "service_worker": "background.js" },
"permissions": ["activeTab", "scripting", "storage", "contextMenus"]
And create background.js:
chrome.runtime.onInstalled.addListener(() => {
chrome.contextMenus.create({
id: 'count-selection',
title: 'Count words in selection',
contexts: ['selection'],
});
});
chrome.contextMenus.onClicked.addListener((info) => {
if (info.menuItemId !== 'count-selection') return;
const words = info.selectionText.split(/\s+/).filter(Boolean).length;
chrome.action.setBadgeText({ text: String(words) });
setTimeout(() => chrome.action.setBadgeText({ text: '' }), 4000);
});
Two MV3 rules show up here:
- Register listeners at the top level of the service worker, not inside callbacks. Chrome stops idle service workers (typically after 30 seconds without events) and restarts them when an event fires. Listeners must be registered synchronously so Chrome can deliver that event.
- Don’t rely on global variables surviving. If you need state, put it in
chrome.storage.
Click reload on the extension card after editing the manifest.
Step 8: Package it for the Web Store
When you’re ready to share it:
- Add icons (16, 48 and 128 px PNGs) and reference them with an
"icons"key in the manifest. Chrome shows a generic letter icon until you do. - Zip the contents of the folder, so
manifest.jsonis at the root of the zip, not inside a subfolder. - Write a single-purpose description, since the Web Store requires every extension to have one clear purpose.
Our guide to publishing on the Chrome Web Store covers fees, review and the most common rejection reasons.
Where to go from here
- Content scripts (
content_scriptsin the manifest) run automatically on matching pages. Powerful, but they need host permissions, which trigger warnings. Use them only when on-click won’t do. - Side panel (
chrome.sidePanel) gives your extension a persistent panel next to the page, which suits note-taking and research tools. - Options page (
options_page) is the place for larger settings screens. - Cross-browser: to run this in Firefox, add a
browser_specific_settings.gecko.idto the manifest and test withabout:debugging.
The key lesson from Reading Time is how much you can do with activeTab. Before you add <all_urls> to any extension, ask whether the user clicking a button first would be acceptable. Most of the time it is, and your users get an install dialog with nothing frightening on it.