Don't Stop at the Web Page: Adding a Browser Extension to Your Vibe Project in Practice
An extension earns its place only if it does one thing the website cannot: save on the spot, nudge at the right moment, or stay open. Three shapes, least permissions, login and sync, release discipline — with a fictional funnel of 1000→420→210→126→63.

Let me say one thing up front: this guide is not about getting your extension into the store. This site already published a piece in October, "From zip file to store page: seven hurdles to launching a browser extension," covering store review, privacy policies, and the first-aid kit for rejections — that one handles "how to launch." This guide covers the other half: once the extension is part of your product, what extra thing does it do for your main site, how do you choose between the three shapes, how do you keep permissions tight, and how do you keep its data in sync with the main site. It runs through one fictional example: "SaveIt", a tool for saving good articles found online to read later, and a fictional user called "A-Nan". Every number, conversation, and scene in the examples is fictional — a drill to make the ideas concrete, not a real product or a real incident. The funnel numbers in the last section are a fictional sample too, used to do the math, not real statistics.
First, figure out what the extension does that the main site cannot
Most people build extensions in the wrong order: they read the extension docs first, follow a tutorial to build a popup, and only then ask what the popup is for. The result is usually a shrunken copy of the web app — a login box, a list, and a search box crammed into a popup, all things the user can already do on the website. Installing the extension only adds one more entry point. An extension like that has no reason to exist. Users install it, forget it in three days, and never recommend it to anyone.
An extension earns its place from exactly one fact: it lives in the browser, while your website lives in one tab. There are things the browser can do that a web page cannot, or can only do awkwardly. Once you see that, the choices narrow to three kinds. The first is "on the spot": the user is reading an article, looking at a product, or scrolling a feed on some other site, and does not want to open your site, copy a link, and paste it to save something — they just want to click once, or select a passage, and have it saved. The second is "a nudge at the right moment": the extension recognizes that the page the user is on relates to your product, and quietly says so — this item dropped in price, you already saved this article, this page has a pending task. The third is "always there": your product needs a small window that stays open, such as a timer, a to-do list, or a clipboard, and the user does not want to keep a tab open just for that.
The "SaveIt" example is typical. A-Nan finds a long article online and wants to read it later. Without the extension, the steps are: copy the link, open the SaveIt website, log in, paste, click save — five steps, and any interruption along the way loses the article. With the extension, the steps are: click the toolbar icon, click save, done. The difference between two steps and five sounds small, but for something done "on the spot", it is the difference between "gets used" and "never gets used". Many users do not lack a need for your product — your product is just too far from what they are doing right now, far enough that they cannot be bothered to go over there.
So before writing any code, write one sentence: "Once the extension is installed, what is the one thing a user can do on other websites that they cannot do now, or can only do with a lot of effort?" If you cannot write that sentence, do not build the extension. Making the web app better is worth more than one more unused extension. If you can write it, every decision after that — shape, permissions, sync — has a test: anything that makes that one thing smoother gets built; anything unrelated, however cool it looks, gets cut first.
Three shapes — do not build all of them at once
Browser extensions commonly take three shapes: a toolbar popup, a widget injected into the page, and a side panel. Each solves a different problem, and each costs a different amount. The most common beginner mistake is wanting all three, and ending up with all three done halfway.
The toolbar popup is the most common shape: click the toolbar icon, a small window appears, and the user saves something, checks a list, or changes a setting inside it. Its strength is that it is simple, self-contained, and never disturbs the page the user is looking at; its weakness is that it disappears the moment it closes, so it is wrong for anything the user needs to stare at for a while. Popups fit "on the spot" actions: save, bookmark, jot a quick note. A-Nan's SaveIt is a popup: click the icon, see the current page's title and summary, click save, and the popup closes by itself — the whole thing takes under three seconds.
Page injection is the second shape: the extension adds a small button, a floating layer, or a highlight to the web page the user has open. It sits closest to what the user is doing, and feels the smoothest; but it is also the most likely to cause trouble. Web pages have wildly different styles, so your widget can be overridden by the page's styles, covered by an ad, or collide with the page's own buttons. More importantly, users feel that you have tampered with their page, which costs the most trust. Page injection is only right for one thing: your product genuinely needs to act on the current page — select-to-translate, highlight, compare prices, remove clutter. Does adding a "save" button to a page count as acting on it? Yes — but that action can also live in the popup, so do not inject.
The side panel is the third shape: a persistent panel opens at the side of the browser, next to the current page. Its strength is that it stays open while the user reads a page and works in the panel side by side; its weakness is that only newer browsers support it well, older users may never find the entry point, and opening it squeezes the page narrower. Side panels fit "always there" scenarios: to-do lists, notes, reading with highlights. If A-Nan only wants to save things on the spot, a side panel is overkill; but if SaveIt later adds "highlight while you read", the side panel becomes the main shape.
The way to choose is unglamorous but works: write down the core action from your one sentence, and ask what the user is doing when it happens. If they are reading something on another site and the action must be quick and light, pick the popup. If the action must hug the content of the current page, pick injection. If the action lasts ten minutes or more and goes back and forth with the page, pick the side panel. When you want all three, build the one that best represents the core action first, ship it, look at the data, and only then decide whether to add a second. The first version of an extension should be as small as possible — small enough to finish, ship, and get real feedback within two weeks.
Permissions: take only what you need, and ask late, not early
Permissions are where extensions most easily lose points. When a user sees "Read and change your data on all websites" on the store page, their first thought is not "this extension is powerful" but "what is it planning to do". Many extensions get uninstalled, delisted, or called out in the press for the same root cause: asking for too much, asking too early, and asking for things they never use.
Start with "only what you need". Browser permissions are granted on demand: if you only need the current tab, do not ask for all websites; if a click can trigger it, do not ask to run in the background; if you only need the title of the page the user just clicked on, do not ask to read the whole page. Take SaveIt as the example: saving the current page only needs the current tab's title and address, and one activeTab permission covers it — there is no need for "read data on all websites". Reading selected text is only needed for saving a selection; reading the page address for comparison is only needed for recognizing "you already saved this". Every permission must be explainable in one sentence on the store page: "We need this permission to do this thing." A permission you cannot explain is a permission you do not need.
Then there is "late beats early". When a user has just installed the extension, you are still a stranger to them. Popping up a pile of permission requests at that moment will most likely get a refusal, or an uninstall. The better way is to ask for nothing extra at install time, let the user start using the extension, and ask for a permission right when they reach the feature that needs it, telling them why it is needed. For example, A-Nan is only asked for permission to read the current tab the first time they click "save", and the prompt says "We need to read this page's title and address so we can save it for you." By then the user already knows what they are trying to do, so the chance of refusal is much lower. The logic is simple: a permission request is not part of the install flow, it is part of the feature — ask for it inside the feature that needs it.
One more rule that is easy to miss: write permission explanations in plain language, not copied from the docs. The privacy statement and permission notes on the store page are what users actually read when deciding whether to install. "This extension sends the address of pages you visit to our server for syncing" is far more useful than "This extension needs host permission." The first tells the user what happens; the second just repeats a technical term. If you cannot explain in plain words what a permission is for, that permission probably should not be requested.
How the extension and the main site keep their data in agreement
An extension is not a second product — it is a second home for your main site. What a user saves in the extension must show up on the website; what they delete on the website must not still sit in the extension. An extension whose data disagrees with the main site is worse than no extension at all: users stop trusting either side, because they cannot tell which one is right.
The most common trap is the login state. The user is already logged in on the website, installs the extension, and is asked to log in again — they will wonder whether you run two separate systems. The right approach is to share one login between the extension and the main site: the first time the extension opens, it asks the main site "do I know this user?" — if yes, just use it; if no, ask them to log in once. The technical details vary, but the experience standard is single: after logging in once on the main site, the user should never see another login box inside the extension.
The second trap is sync timing. A user taps save on the subway, on a plane, or somewhere with a weak signal. The extension must not silently drop that save because there was no network, and must not pretend it succeeded when nothing was stored. The right approach is to record the save locally first, tell the user "Saved locally, will sync when you are back online," and then sync quietly once the network returns, marking the local record as synced. Users do not need to know terms like "local queue" or "conflict resolution" — they only need to know one thing: no save they tapped was ever wasted.
The third trap is conflict. A user edits a title in the extension while also editing the same title on the website, and the two versions differ — whose wins? The simplest rule is to let the later edit win and keep the earlier one in history, where the user can always find it. The rule is not perfect, but it is simple, explainable, and recoverable when things go wrong. Never build complicated auto-merging in the first version: two versions merged automatically sounds clever, but once it ships, users will have no idea which version they are looking at, and neither will you when something breaks. Get to "never lose data" first; "merge beautifully" comes later.
One more detail: what the extension shows should be "enough, and no more". A popup is small. It cannot hold everything the website does, and it should not try. Inside the popup, A-Nan only needs three things: save the current page, see the five most recent saves, and search by keyword. Full lists, category management, and bulk actions all belong back on the website. The popup is the "on the spot" place, not the office. Turning the popup into a shrunken copy of the website is the most common way for an extension to die.
Updates and rollbacks: shipping is when it starts
Once an extension ships, the store handles distribution for you, but it will not handle "what if this release is broken". When a web app ships broken, you can ship a fix immediately and users get it on refresh. When an extension ships broken, the version on users' machines does not update instantly, and the new version still has to pass store review — in between, all you can do is watch users run the broken version. So release discipline for extensions has to be stricter than for web apps.
The first rule is: do not hard-code critical logic into the extension. Decisions like "can this page be saved", prompt text, and feature switches should be fetched from your server, not baked into the extension code. That way, if a website redesign breaks your extension, you can turn that feature off from the server side without waiting for store review. The finer the switches, the better: per site, per feature, per version, each switchable on its own.
The second rule is: roll a new feature out to a small slice of users first. Extension stores generally support staged rollouts — give it to ten percent of users, watch for a day or two, and only then push it to everyone. During those two days, watch very specific things: crash counts for the new version, uninstall counts, and whether anyone reports "I cannot save anymore". The moment a number looks wrong, stop — do not rush it out to everyone. A web app can afford "ship it and see"; an extension cannot, because rolling an extension back costs far more than rolling a web app back.
The third rule is: write release notes that say what actually changed. Many extensions ship with empty release notes, or "fixed some issues". A user installs the update, opens the extension, finds the interface changed and a button moved, and assumes something broke. Release notes do not need to be long — three sentences are enough: what was added, what changed, what was fixed. While writing them, ask yourself: if the user never reads the notes, can they still discover the new feature on their own? If not, the new feature's entry point is buried too deep.
One last note for beginners: being delisted is not the end of the world, but take it seriously. The common causes are few: unclear permission explanations, a missing privacy policy, a description that does not match what the extension actually does, or a user report. When a delisting notice arrives, read the specific reason it gives, fix that reason, and resubmit — do not republish the identical extension under a new name. That is the behavior stores dislike most, and the fastest way to a permanent ban. The store-launch guide on this site has a first-aid kit for rejections that covers this stretch; this guide does not repeat it — follow that one when it happens.
Doing the math: the funnel from store page to weekly use
How good an extension is cannot be judged by install counts alone. Installs can look great while nobody actually uses what they installed — which is the same as not installing it at all. The numbers below are a fictional sample, describing SaveIt's first month: 1000 people open the store page, 420 of them click install, 210 of those authorize and log in, 126 of the logged-in users actually save something with the extension in the first week, and 63 of them stay and save with the extension at least once a week.
The step-by-step rates work out like this: install rate is 420 out of 1000, or 42 percent; login rate is 210 out of 420, or 50 percent; first-week use rate is 126 out of 210, or 60 percent; weekly retention is 63 out of 126, or 50 percent. The overall rate is 63 out of 1000, or 6.3 percent. The books balance: 1000 minus 420 loses 580 people; 420 minus 210 loses 210; 210 minus 126 loses 84; 126 minus 63 loses 63; and 63 remain. 580 plus 210 plus 84 plus 63 plus 63 is exactly 1000, to the person.
The most useful part of this funnel is not the last box, but the 580 people lost between the first box and the second. A store-page-to-install rate of only 42 percent means the store page itself has a problem: the screenshots do not explain what the extension does, the permission notes scare people off, or users read for a while and still cannot tell "how is this different from the website". Many people see low installs and immediately buy ads or post everywhere for traffic — but the funnel says: fix the store page first. Moving 42 percent to 50 percent is worth more than doubling your traffic.
Between the second box and the third, 210 people installed but never logged in — half of them. The two most common causes are: the login flow is too winding — the user clicks login in the extension, gets bounced to the website, logs in, and never finds their way back; or the user never knew the extension needed a login at all, clicked once, saw nothing happen, and never clicked again. The fix is direct: make login a one-step job inside the extension, tell the user right away "Done, you can save now," and hand them one successful save — let them save the current page with their own hands and see the words "Saved". Then they know how it works.
Between the third box and the fourth, 84 people logged in but never used it in the first week. These 84 are not people who dislike your product — they forgot. An extension sits in the toolbar; out of sight, out of mind, especially when the user is busy. The fix is not to pester them with notifications, but to put the extension next to what they are already doing: when they open a long article, the extension quietly offers "Save this to read later," or when they open the same article for the third time, it reminds them "You have opened this three times — want to save it?" A nudge belongs in the moment the user needs it, not the moment you remember them.
The last box, 63 people who use it every week, is a small number — but it is the most valuable number. These 63 are the people the extension genuinely serves. They come back to your product every week, even if only to tap save once. The value of an extension is not in its install count, but in these 63 people. Fixing each step of the funnel is worth far more than staring at the last box and sighing about low retention.
Pre-launch checklist: ten items, tick them off one by one
First, write that one sentence: once the extension is installed, what is the one thing a user can do on other websites that they cannot do now, or can only do with a lot of effort? If you cannot write it, do not build it. Second, pick only one shape — build the one that best represents the core action first. Third, go through the permission list item by item: every permission must be explainable to the user in one sentence; delete any you cannot explain. Fourth, do not ask for permissions at install time; ask inside the feature that actually needs them. Fifth, share one login between the extension and the main site, so a user who logged in on the main site never sees another login box in the extension. Sixth, make offline saves work first: with no network, record locally and sync quietly later — never pretend a save succeeded. Seventh, resolve conflicts by time: the later edit wins, the earlier one goes into history. Eighth, keep critical logic and feature switches on the server, not hard-coded into the extension. Ninth, roll out in stages to a small slice of users first, watching crash counts and uninstall counts before going to everyone. Tenth, write release notes in three sentences: what was added, what changed, what was fixed.
None of these ten is hard. The hard part is doing every one of them when a deadline is pressing. An extension is slow work: it lives in the user's browser, closer to the user than anything else you build — and closer to their suspicion. One extra permission buys one more unit of doubt; one lost sync costs one unit of trust. But once an extension is done right, it is the closest your product ever gets to the user: they can use it without opening your website at all. A-Nan later built a habit: when he sees a good article, he taps the extension to save it, and reads it on the sofa in the evening. Nobody taught him that habit — the extension made it effortless, so the habit formed by itself. That is all your extension has to do: take something the user already wants to do, and make it effortless.
Comments (0)
Sources
Related articles
The main thread has to draw the page and do the accounts, so it freezes the moment the work gets heavy. A worker is another thread in another global context, and the two sides talk only through messages. Following MDN's Using Web Workers and Worker docs: new Worker, postMessage and onmessage, structured-clone copying, what a worker can and cannot do, onerror and terminate(), SharedWorker, and transferable zero-copy — with a 100-mistake breakdown from a fictional cafe order page.
setTimeout handles once, setInterval handles repeatedly — but delay only promises "at least this long": 0 is not immediate, background tabs run even later, and anything over 2147483647 overflows. Following MDN's setTimeout and setInterval docs: async return, argument passing, the delay rules, the 4 ms nesting clamp, clearTimeout and clearInterval, recursive setTimeout, lost this, and string arguments — with a 100-mistake breakdown from a fictional cafe order page.
An array has to be computed all at once; a generator hands out one value at a time, only when asked. Following MDN's Iterators and generators, function*, and Generator docs: the next() protocol, function* and yield, for...of consumption, Symbol.iterator, yield* delegation, sending values in with next(x), throw() and return(), and when to use a generator at all — with a 100-mistake breakdown from a fictional cafe order page.