9 min read
Building a Chrome plugin is one of the fastest ways to ship something real that people use every day inside their browser. The learning curve is gentler than most developers expect, and the Chrome Web Store gives you a distribution channel that’s already in front of billions of people. Here’s everything you need to get from zero to a working, published extension.
What a Chrome Plugin Actually Is
The terms “Chrome plugin” and “Chrome extension” are used interchangeably by most people, so let’s clear that up fast. Google officially deprecated NPAPI plugins years ago. What people mean today when they say “build a Chrome plugin” is a Chrome extension: a package of web files (HTML, CSS, JavaScript) that runs inside the browser and can interact with pages, tabs, and browser APIs.
From the studio
We build apps people actually keep.Tinkrd is a small indie studio making focused, high-quality apps for everyday life. See what we're working on.
View our appsEvery extension is built around a manifest file that tells Chrome what the extension does, what permissions it needs, and which scripts to load. That’s the foundation. Everything else, the popup UI, the background logic, the content scripts that touch web pages, hangs off that one file.
If you want a deeper look at the full scope of what extension development involves before you start writing code, the Chrome extension development overview covers the landscape well, including Manifest V3 changes that affect every new build today.
The Core Files Every Extension Needs
You don’t need a framework or a build tool to start. A working extension can be three files in a folder. Understanding what each piece does will save you hours of confusion later.
manifest.json
This is the only required file. It tells Chrome everything about your extension: its name, version, what permissions it requests, and which scripts and pages to load. Chrome currently requires Manifest Version 3 (MV3) for all new submissions.
{
"manifest_version": 3,
"name": "My First Extension",
"version": "1.0",
"description": "Does something useful.",
"permissions": ["activeTab", "storage"],
"action": {
"default_popup": "popup.html",
"default_icon": "icon.png"
},
"background": {
"service_worker": "background.js"
},
"content_scripts": [
{
"matches": [""],
"js": ["content.js"]
}
]
}
popup.html and popup.js
This is the small window that appears when a user clicks your extension icon. It’s a normal HTML file. You write the UI in HTML and CSS, and link a JavaScript file for behavior. One important rule: no inline scripts. MV3 requires all JavaScript to live in separate files, so no onclick attributes and no <script> tags with inline code.
background.js (service worker)
This is where logic lives that needs to run independently of any specific tab or page. In MV3, the background page became a service worker, which means it can be terminated by Chrome when idle and restarted when needed. Don’t rely on it to hold persistent state in memory. Use chrome.storage instead.
content.js
Content scripts are injected into web pages and can read and modify the DOM. They run in an isolated JavaScript context, so they can’t directly call functions on the page and can’t access most Chrome APIs directly. They communicate with the background service worker using chrome.runtime.sendMessage.
// content.js
chrome.runtime.sendMessage({ action: 'pageLoaded', url: location.href },
function(response) {
console.log('Background replied:', response);
}
);
// background.js
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
if (message.action === 'pageLoaded') {
console.log('Page loaded:', message.url);
sendResponse({ status: 'received' });
}
});
Setting Up Your Development Environment
You don’t need much. A code editor, Chrome, and a terminal if you want to use a build tool. Here’s an honest look at your options depending on where you’re starting from.
| Approach | Best for | Tools needed | Build step? |
|---|---|---|---|
| Vanilla JS (plain files) | First extension, simple tools | VS Code or any editor | No |
| Vite + React | Complex UI in the popup or options page | Node.js, npm, vite-plugin-web-extension | Yes |
| Plasmo framework | Faster scaffolding, TypeScript out of the box | Node.js, npm | Yes |
| CRXJS + Vite | Hot module reload during development | Node.js, npm | Yes |
For a first extension, start with plain files. The feedback loop is instant and you won’t spend the first hour debugging webpack. Once you understand how all the pieces connect, adding a build tool is straightforward.
To load your extension while you’re building it, go to chrome://extensions, turn on Developer Mode in the top right, and click “Load unpacked.” Point it at your extension folder. Every time you change a file, click the refresh icon on the extension card and reload the tab you’re testing on.
Permissions: Only Ask for What You Need
Permissions are where a lot of first-time extension developers go wrong. Requesting too many permissions will get your extension rejected during review or, worse, it will make users hesitant to install it. The Chrome Web Store review team pays close attention to permission justification.
The most common permissions and what they actually allow:
- activeTab: Access to the current tab when the user clicks your extension icon. Less invasive than broad host permissions. Use this when you only need to act on the page the user is already on.
- storage: Read and write to
chrome.storage.localorchrome.storage.sync. Sync storage is limited to around 100KB total and syncs across devices when the user is signed into Chrome. - tabs: Access to tab metadata like URLs and titles across all tabs. This triggers a warning to users, so only request it if you genuinely need it.
- scripting: Lets you inject scripts programmatically using
chrome.scripting.executeScript. Required in MV3 if you need dynamic injection rather than static content scripts. - host permissions: Access to specific domains or all URLs. Broad host permissions like
<all_urls>get the most scrutiny during review and the most friction with users.
A good rule: start with the minimum, ship it, and add permissions only when a real feature requires them.
Storing Data and Talking Between Extension Parts
One of the trickier parts of building a Chrome plugin is understanding the different execution contexts and how data moves between them. Your popup, your content script, and your service worker are all separate environments. They don’t share memory.
chrome.storage vs localStorage
Don’t use localStorage for extension data. It’s scoped to a specific origin and won’t be accessible across all parts of your extension reliably. Use chrome.storage.local for anything that should persist, and chrome.storage.sync if you want it to follow the user across devices.
// Save data
chrome.storage.local.set({ userPreference: 'dark' }, function() {
console.log('Saved.');
});
// Read data
chrome.storage.local.get(['userPreference'], function(result) {
console.log('Preference:', result.userPreference);
});
Message passing
When a content script needs to trigger something in the background, or when your popup needs data from the current page, you use message passing. Keep your messages simple: an action name and a payload. Don’t try to pass complex objects or functions.
If you need the popup to request data that requires reading the page, the flow is: popup sends message to background, background uses chrome.scripting.executeScript to run a function in the content context, and returns the result. This is more verbose than you’d expect, but it’s the right pattern in MV3.
Getting Your Extension Into the Chrome Web Store
Publishing is a step that surprises a lot of developers with its requirements and review time. Here’s what to expect.
What you need before you submit
- A Google developer account. There’s a one-time $5 registration fee.
- A zip of your extension folder (not a zip of a folder containing your folder, just the files themselves).
- At least one screenshot at 1280×800 or 640×400.
- A 128×128 icon in PNG format.
- A privacy policy URL if your extension handles any user data, which is most extensions given that even
storagepermission can count. - A clear justification for every permission you request. Write this in the “Single purpose” and permission justification fields. Be specific.
The review process
Initial reviews for new extensions typically take a few days, though they can stretch longer. Extensions that request sensitive permissions or that involve account login, payments, or data collection get more scrutiny. If your extension is rejected, the rejection notice will cite specific policy violations. Read the Chrome Web Store developer policies before you submit, not after.
One thing worth knowing: Tinkrd, the studio behind the Stepping Stones app, went through a similar ramp-up process understanding app store policies when launching on mobile. The Chrome Web Store review process rhymes with Apple and Google Play in a lot of ways, so if you’ve shipped a mobile app before, you’ll recognize the pattern.
For a full walkthrough of the build and ship process including the common pitfalls first-time extension developers hit, the guide to building a Chrome extension covers the step-by-step in more detail.
If this is your first time shipping any kind of app product, the broader context in the indie app development journey from idea to launch is worth reading alongside the technical steps.
Frequently asked questions
Is building a Chrome plugin the same as building a Chrome extension?
Yes, in practice they mean the same thing today. Google deprecated traditional browser plugins (NPAPI) years ago. When developers say “Chrome plugin” now, they mean a Chrome extension built with HTML, CSS, and JavaScript using the Chrome Extensions API.
Do I need to know React or a framework to build a Chrome extension?
No. Vanilla JavaScript works fine and is actually easier to start with because there’s no build step. Frameworks like React are useful if your popup UI is complex or if you’re building an extension with multiple pages, but they add setup overhead that isn’t worth it for a simple first project.
How long does Chrome Web Store review take?
For new extensions, typically two to seven business days. Updates to existing extensions are often faster. Extensions requesting sensitive permissions can take longer. Submitting on a Friday or during a holiday period tends to slow things down too.
Can I monetize a Chrome extension?
Yes. The most common approaches are a one-time purchase, a subscription handled outside the store (using Stripe or similar), or a freemium model where the extension is free but unlocks paid features. The Chrome Web Store does not take a cut the way mobile app stores do, but it also doesn’t have built-in payment infrastructure, so you handle billing yourself.
What’s the difference between Manifest V2 and Manifest V3?
MV3 is the current required version for new Chrome Web Store submissions. The biggest change is that the persistent background page became a short-lived service worker, which means you can’t rely on background state staying in memory. MV3 also restricts certain API patterns that were used by ad blockers and some automation extensions. If you’re starting fresh, build for MV3 from day one.
Building a Chrome plugin is genuinely approachable for any developer who knows JavaScript, and the path from first file to published listing is shorter than most people assume. Start small, get something loading in the browser today, and iterate from there rather than planning a perfect architecture before you’ve written a line.
We’re building in the open
Tinkrd is a small studio making thoughtful apps for families. Our first app is launching soon.