Developer

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: 3 tells Chrome to use the current extension platform. MV2 extensions no longer run in Chrome.
  • action is the toolbar button. default_popup is the small page that opens when you click it.
  • permissions:
    • activeTab grants 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.
    • scripting lets us run a function inside that page.
    • storage lets us save the reading-speed setting.
  • commands → _execute_action is a special command name that opens the popup with a keyboard shortcut. A shortcut also counts as invoking the extension, so activeTab applies.

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 the countWords function and runs it in the page. That’s why it can’t use variables from the popup. Anything it needs must be passed with args. Its return value comes back to the popup.
  • chrome.tabs.query works without the tabs permission. We only use tab.id, and we don’t read the URL or title, which would need tabs and trigger the “Read your browsing history” warning.
  • chrome.storage.sync stores small settings and syncs them through the user’s Chrome account. For larger data, use chrome.storage.local.
  • Every Chrome extension API used here returns a Promise in MV3, so async/await works everywhere.
  • Since Chrome 148 you can also write browser.storage.sync.get(...) instead of chrome.…. Chrome now supports the standard browser namespace (docs), which makes porting to Firefox easier. This guide keeps chrome.* because it works in every Chromium browser people are likely to have.

Step 4: Load it in Chrome

  1. Open chrome://extensions.
  2. Turn on Developer mode (top right).
  3. Click Load unpacked and select your reading-time folder.
  4. Click the puzzle-piece icon in the toolbar and pin Reading Time.
  5. 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 the catch block doing its job.
  • A PDF: Chrome’s PDF viewer isn’t a normal page, so it also lands in the catch.
  • A huge page: innerText forces layout, which can be slow on very large pages. For a production extension you might count words from textContent instead, 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.json is 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_scripts in 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.id to the manifest and test with about: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.

Keep reading