How to build a Chrome extension with Manifest V3, from first file to store

What is a Chrome extension made of?

A Chrome extension is a folder of web files. Google’s getting started page says you build extensions with the same web technologies used for web apps: HTML, CSS and JavaScript. On top of the normal web APIs, extensions get the Chrome Extension APIs for things like tabs, storage and injecting scripts.

The only required file is manifest.json. Per Google’s manifest reference, it must sit in the extension’s root directory, and it records metadata, declares permissions and says which files run in the background and on the page. Everything else depends on what the extension does:

Manifest V3 is the current platform version. Google’s Manifest V3 overview says background pages became service workers, and that an extension can only execute JavaScript that is included in its package. No remotely hosted code means no loading a script from your server at runtime, so you cannot paste a URL to a script and expect it to run.

How do you build a working extension in ten minutes?

Build something tiny that uses a real API. This extension adds a toolbar button that counts the words on the page you are viewing. It needs one manifest, one HTML file and one script. Make a new folder and create the three files.

{
  "manifest_version": 3,
  "name": "Word Counter",
  "version": "1.0.0",
  "description": "Counts the words on the page you are viewing.",
  "action": {
    "default_popup": "popup.html"
  },
  "permissions": ["activeTab", "scripting"]
}

<!doctype html>
<html>
  <body style="width: 220px; padding: 12px; font: 14px system-ui">
    <button id="count">Count words on this page</button>
    <p id="out"></p>
    <script src="popup.js"></script>
  </body>
</html>

document.getElementById("count").addEventListener("click", async () => {
  const out = document.getElementById("out");
  try {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    const [{ result }] = await chrome.scripting.executeScript({
      target: { tabId: tab.id },
      func: () => document.body.innerText.trim().split(/\s+/).length,
    });
    out.textContent = result + " words";
  } catch (err) {
    out.textContent = "Cannot read this page.";
  }
});

Two choices in that code are worth understanding. The script is in its own file because Manifest V3 extension pages do not run inline scripts. And the manifest asks for activeTab rather than access to every site: Google’s activeTab documentation says it gives temporary access to the current tab when the user invokes the extension, for example by clicking its action. The catch handles pages Chrome does not let extensions read, such as the Chrome Web Store itself and chrome:// pages.

Now load it, following Google’s Hello World tutorial:

1. Open chrome://extensions in a new tab.
2. Turn on Developer mode with the toggle.
3. Click Load unpacked and select your folder.
4. Pin the extension from the puzzle-piece menu, open any article and click the button.
5. After every code change, return to chrome://extensions and click the reload icon on the extension card.

If an extension has no icons in the manifest, Chrome creates a generic one, which is fine for testing. For popup errors, the same tutorial explains that you open the popup’s own console, separate from the page’s console.

How do you change a page automatically with a content script?

A popup waits for a click. A content script runs by itself on every page whose address matches the patterns you declare. This second extension shows an estimated reading time on English Wikipedia articles. It uses 200 words a minute, which is an assumption rather than a standard, so change it freely.

{
  "manifest_version": 3,
  "name": "Reading Time Badge",
  "version": "1.0.0",
  "description": "Shows an estimated reading time on Wikipedia articles.",
  "content_scripts": [
    {
      "matches": ["https://en.wikipedia.org/wiki/*"],
      "js": ["content.js"]
    }
  ]
}

const article = document.querySelector("#mw-content-text");
if (article) {
  const words = article.innerText.trim().split(/\s+/).length;
  const minutes = Math.max(1, Math.round(words / 200));
  const badge = document.createElement("div");
  badge.textContent = minutes + " min read";
  badge.style.cssText =
    "position:fixed;top:8px;right:8px;z-index:99999;padding:4px 8px;" +
    "background:#222;color:#fff;font:12px system-ui;border-radius:4px";
  document.body.append(badge);
}

Notice that this version declares no permissions at all. The matches pattern is what grants it access, and it tells reviewers and users exactly which sites it touches. Keep that pattern as narrow as the feature allows.

One safety habit to build now: when you insert text coming from a page, set textContent, not innerHTML. Page content is untrusted, and putting it into HTML is how an extension becomes a way to attack the sites its users visit.

Can you build a Chrome extension with an AI coding agent?

Yes, and extensions suit it: the project is small, a few files, and the feedback loop is quick. The risk is that a model drawing on older examples may write Manifest V2 code, such as a background.page entry or chrome.browserAction, which does not load. Tell the agent the rules in the brief.

Build a Chrome extension called [name] using Manifest V3, plain JavaScript, no build step, no framework.

User: [one specific person and when they need this].
Job: [the one thing the extension does, in one sentence].
Trigger: [user clicks the toolbar button / it runs automatically on [site pattern]].

Rules:
- manifest_version must be 3. Do not use Manifest V2 APIs such as chrome.browserAction or background pages.
- Request the fewest permissions possible. Prefer activeTab over host permissions. Tell me why for each permission you add.
- No remotely hosted code, no eval, no inline scripts in HTML. All JavaScript is in files in the package.
- Never use innerHTML with page text. Use textContent.
- Store settings with chrome.storage, not cookies.
- Do not send any data to a server. If you think a server is needed, stop and ask.

Out of scope: accounts, payments, analytics, options page, other browsers.

Before writing code, list the files and the permissions you will use, then wait for my go-ahead. After each step, tell me how to reload the extension at chrome://extensions and what I should see.

Read the manifest after every change. That one file shows which permissions and sites the agent added. For the general working method see the AI coding agent guide, and for what to put in a brief see how to write an app build prompt.

Want a starting point? One idea posted on the board, Turn the tab you have open into three questions tomorrow, is a job that begins with reading the page in the active tab, which is exactly what the first extension above does. More in the chrome extension ideas list and on the board.

How do you publish a Chrome extension on the Chrome Web Store?

Publishing is a form-filling job, and it starts with your manifest. Google’s prepare your extension page says you cannot edit the manifest metadata after uploading, so a typo means changing the file, raising the version number and zipping again. Check these fields first:

• name appears in the store and in the browser.
• description can be no more than 132 characters.
• icons lists your icon files. Google’s minimal manifest example uses 48 and 128 pixel sizes.
• version must be higher with every upload. Start low so you have room.

1. Zip the extension. Put the manifest in the root of the zip, not inside a folder.
2. Register as a developer. Google’s registration page says you must register in the developer dashboard and pay a one-time registration fee; the amount is shown at the payment step. Use an email you check often, since it cannot be changed after the account is created.
3. Upload. In the developer dashboard click Add new item, choose your zip and upload it. Google lists a 2 GB maximum package size.
4. Complete the tabs. Google’s publish guide names them: Package, Store Listing, Privacy, Distribution and Test instructions. On the Privacy tab you declare your extension’s single purpose and how it handles user data.
5. Submit for review. The dialog lets you choose to publish automatically after review or to defer publishing. If you defer, Google says you have up to 30 days to publish before the submission reverts to a draft.

Google’s guidance on the Privacy tab says an extension must have a single purpose that is narrow and easy to understand, and that it should request the minimum permissions consistent with that purpose. Requesting broader permissions than necessary may cause rejection. That is why the permissions in the examples above are so short.

Google’s review process page says most extensions are reviewed within a few days but it can take up to a few weeks, and suggests contacting developer support if an extension has been pending more than three weeks. The publish guide also says a new publisher is limited to two published extensions at first, and you can request an increase from the dashboard.

If you decide not to build your idea, post it on the board. It is free and needs no account.