Forem: Himanshu

How to Secure API Keys in Chrome Extension?

Himanshu — Wed, 24 Dec 2025 16:19:45 +0000

Here’s how i handle my API keys, like OpenAI keys, Gemini keys, Stripe Keys in my chrome extension

Why You Can't Put API Keys in Client-Side Code?

Let's get this out of the way first: never, ever put your API keys directly in your Chrome extension's client-side code. Here's why:

The Core Problem

When someone installs your Chrome extension from the Web Store, they're downloading the exact same files you uploaded. Yes, that means:

All your JavaScript/TypeScript code
All your configuration files
And yes, any API keys you've included
here’s the entire source code of Grammarly (hahahaha)

.env file will protect me? Not really.

When you build your extension, those environment variables get bundled into your code. Anyone can:

Right-click your extension
Click "Manage Extensions"
Click "Details"
Find the extension's folder on their computer
Open your bundled JavaScript files
Search for your API key

It takes less than 30 seconds.

What Happens When Keys Are Exposed?

Once your API key is compromised:

OpenAI/Gemini: Someone could rack up thousands of dollars in API costs on your account
Mailgun: Spammers could use your account to send malicious emails
Any paid API: Your credit card becomes their unlimited resource

What About WebAssembly (WASM)?

You might have heard about hiding keys in WebAssembly. While WASM does obfuscate your code, it's not a security solution:

WASM can still be decompiled with tools
It adds complexity to your development workflow
It's fragile and can break with browser updates
Chrome web store’s reviewing team will not like this

Don't waste your time with WASM for API key protection. There's a better way.

The Right Way: Use a Backend Proxy (It's Easier Than You Think)

I know you hate to hear this and i hate to say this but: API keys should only live on the server, never on the client side.

but relax… we have an easy option which is Serverless functions, when you hear the word “serverless” it’s not like an all-time running machine that you need to purchase and then install arch on it and then deploy it on IBM’s servers and pay monthly electricity bills and protect it from bitcoin minors….

serverless functions live and die quickly and you don't need to manage them, even though they also run on real servers but they are managed by cloud providers (like vercel, cloudflare, etc) and they are mostly free.

What actually is a Serverless Function?

a serverless function is just a javascript function that will run whenever you call it from your frontend application (chrome extension) using fetch() method (same as you call any api endpoint, an api endpoint is just an ugly looking url that your cloud provider will give you when you upload/deploy your javascript function there :)

you have soo many options and most of them have a free tier, like:

vercel
netlify
supabase functions
Appwrite
cloudflare (pretty scary for beginners but the most cheapest one in this list)
AWS Lambda (i can’t even find their pricing page, just kidding :)

see, these providers don’t only provide serverless functions, they have other billion things too, but you can still only deploy your functions and ignore rest of the fuss and they will give you an api endpoint (url) for free, don't even need to purchase a domain (though you can do it)

let’s take vercel as example,

first create a very minimal NextJs project and then

Step 2: Create Your Vercel Project

Go to vercel.com and sign up
Create a new project
You can start from scratch or connect a GitHub repo

Step 2: Example of a Serverless Function

Create a file at /api/chat.ts in your project:

// app/api/chat.js

export default async function handler() {
    try {
    // Call OpenAI API with YOUR key
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}` 👈
      },
      body: JSON.stringify({
        model: 'gpt-3.5-turbo',
        messages: [{ role: 'user', content: message }]
      })
    });

    const data = await response.json();
    return res.status(200).json(data);
  } 

  /// rest of the code
}

Now you can add your keys in this project’s .env file or:

Go to your project settings in Vercel
Navigate to "Environment Variables"
Add OPENAI_API_KEY with your actual API key
Save it

Step 4: Call It from Your Extension

In your Chrome extension's popup/content script/background script:

// In your extension
async function getChatResponse(message) {

const API_ENDPOINT = 'https://your-project.vercel.app/api/chat' 👈 // vercel will give you this url when you deploy your project, for free

  const response = await fetch(API_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message })
  });

  return await response.json();
}

Supabase as database

now here’s the thing, if you are using supabase or firebase as your database they give you publishable api keys (meaning you can put these api keys on dark website, doesn't matter that much :)

It's meant to be public
Supabase has Row Level Security (RLS) that protects your data (you need to enable and write it manually btw)
All security happens on the server side through RLS policies

So in your Chrome extension, this is perfectly safe:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-publishable-key' // This is safe to expose!
);

that’s pretty much it,

that was a reeeeeally basic blog, but i wish somebody told me all these things when i was starting my extension journey so yeah,

btw if you don’t want to setup all the serverless functions, stripe payments, login/signup, etc, you can checkout my production-ready boilerplate, it’s called extFast

thankyou so much for reading 💛

bye bye :)

What's the Difference Between Manifest V2 and V3 in browser extensions?

Himanshu — Tue, 23 Dec 2025 09:41:34 +0000

alright so you're building a browser extension and everyone's talking about Manifest V3, V4, V5, Vinfinity…

but in firefox world everyone is still using manifest V2, whyyyyyyy and does Firefox support manifest V3?

let’s break it down and understand the difference between the manifest version 3 (chrome) and manifest version 2 (firefox) in browser extensions

One quick thing, i created a chrome extension boilerplate that lets you ship & monetize your extension fast (includes auth, payments, and everything you need). if you are interested, It’s called extFast

What Are Manifests Anyway?

Before diving into the differences, let's quickly cover the basics. Every browser extension needs a manifest.json file, it's like the blueprint that tells the browser what your extension does, what permissions it needs, and name, logo, description etc.

Manifest V2 was introduced in 2012 and has been the standard for over a decade. Manifest V3, announced by Google in 2020, represents a major architectural change that Google claims improves security, privacy, and performance, though i think they introduced V3 and killed V2 because of ad blockers (not really much interesting in new V3, it only s*cks more)

Timeline and Browser Support

Important dates:

Chrome stopped accepting new Manifest V2 extensions in January 2022
Chrome Web Store phased out Manifest V2 in June 2024
Firefox still supports both V2 and V3, with no immediate deprecation plans, source

This means if you're building a new extension for Chrome today, you must use Manifest V3. Firefox developers have more flexibility (you can use Manifest V2, in fact this is a big pain and if you are not using an extension development framework like WXT then you need to manually adjust the extension for firefox v2).

Major Architectural Changes

1. Background Scripts → Service Workers

This is perhaps the biggest change and affects how your extension runs in the background.

Manifest V2: Persistent Background Pages

{
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  }
}

In V2, background scripts ran continuously in a hidden page. They had access to the DOM, could use window and document objects, and stayed alive as long as the browser was open.

Manifest V3: Service Workers

{
  "background": {
    "service_worker": "background.js"
  }
}

In V3, background scripts are replaced by service workers that are event-driven and non-persistent. They start when needed (like when you send a message from your content script), handle events, and then shut down after a period of inactivity (typically 10-30 seconds in Chrome).

What this means for you:

No DOM access: Service workers don't have access to window, document, or DOM APIs
No persistent state: Variables don't persist between service worker restarts (like Map() or Set())
Event-driven: Your code only runs in response to specific events
Frequent restarts: Your service worker will start and stop many times during a browser session

Migration example:

// ❌ Manifest V2 approach
let userSettings = {}; // This won't persist in V3

chrome.runtime.onMessage.addListener((message) => {
  userSettings = message.settings; // Lost when service worker stops
});

// ✅ Manifest V3 approach (use local storage)
chrome.runtime.onMessage.addListener((message) => {
  chrome.storage.local.set({ userSettings: message.settings });
});

2. Host Permissions: Critical Browser Differences

This is where Chrome and Firefox differ significantly, and it's important to understand both.

Manifest V2 (Firefox):

{
  "permissions": [
    "storage",
    "tabs",
    "https://api.example.com/*"
  ]
}

In Firefox with V2, you need to declare API endpoints in the permissions array to make API requests to them, other it will throw errors i guess.

Manifest V3 (Chrome):

{
  "permissions": [
    "storage",
    "scripting"
  ]
}

Here's the crucial difference: In Chrome with Manifest V3, you don't need to declare API endpoints in permissions or host_permissions just to make fetch/API requests to them. Host permissions in Chrome V3 are only required if you want to:

Inject content scripts into pages, source
Access cookies from specific domains

Example - Making API Requests:

// ✅ Works in Chrome V3 without any host_permissions
const response = await fetch('https://api.example.com/data');
const data = await response.json();

// ❌ In Firefox V2, you'd need "https://api.example.com/*" in permissions

Chrome V3 is more permissive with outbound API requests, while Firefox V2 requires explicit permission declarations.

4. Web Accessible Resources

V3 requires you to specify which resources can be accessed by web pages.

Manifest V2:

{
  "web_accessible_resources": [
    "images/*.png"
  ]
}

Manifest V3:

{
  "web_accessible_resources": [
    {
      "resources": ["images/*.png"],
      "matches": ["https://example.com/*"] 👈
    }
  ]
}

This prevents other websites from detecting your extension by trying to access its resources (files).

Offscreen Documents

Since service workers are non-persistent and restart frequently, V3 introduces offscreen documents to handle scenarios where you need persistent state or background processing.

What are offscreen documents?
Offscreen documents are hidden HTML pages that run in a separate context. They're particularly useful for:

Persistent state that survives service worker restarts
Background processing e.g. using the WORKERS reason
Computationally intensive tasks
Certain Web APIs that require a document context (like clipboard access)

// Create an offscreen document for background processing
await chrome.offscreen.createDocument({
  url: 'offscreen.html',
  reasons: ['WORKERS'],
  justification: 'Maintain dictionary lookup cache'
});

// Service worker can communicate with offscreen document
chrome.runtime.sendMessage({
  action: 'lookup',
  word: 'example'
});

Example: Dictionary Lookup with Persistent State

// offscreen.html script
const dictionaryCache = new Map();

// Process expensive lookups and cache results
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'lookup') {
    // Check if we have it cached
    if (dictionaryCache.has(message.word)) {
      sendResponse({ result: dictionaryCache.get(message.word) });
      return;
    }

    // Perform expensive lookup/processing
    const result = performExpensiveLookup(message.word);

    // Cache it for future requests
    dictionaryCache.set(message.word, result);

    sendResponse({ result });
  }
  return true;
});

function performExpensiveLookup(word: string) {
  // Heavy processing that would slow down service worker
  // This state persists even when service worker restarts
  return { definition: '...', synonyms: ['...'] };
}

The key advantage here is that the new Map() object and its data persist as long as the offscreen document is alive, surviving multiple service worker restarts. This is perfect for caching, maintaining lookup tables, or keeping any state that would be expensive to recreate.

Action API Changes

Manifest V2: Had separate browser_action and page_action

"browser_action": {
    "default_title": "your extension name",
    "default_popup": "popup.html"
  },

Manifest V3: Unified into single action API

{
  "action": {
    "default_title": "your extension name",
    "default_popup": "popup.html",
  }
}

Promises Instead of Callbacks

V3 APIs support promises, making async code cleaner.

Manifest V2:

chrome.storage.local.get(['key'], (result) => {
  console.log(result.key);
});

Manifest V3:

const result = await chrome.storage.local.get(['key']);
console.log(result.key);

Note: Chrome still supports callbacks for backward compatibility, but promises are preferred.

Complete Manifest Comparison

Here's a side-by-side comparison of a basic manifest file:

Manifest V2 (firefox):

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0",
  "description": "Extension description",
  "permissions": [
    "storage",
    "tabs",
    "https://api.example.com/*"
  ],
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  },

  "browser_action": {
    "default_popup": "popup.html"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"]
  }]
}

If persistent: true, the background script stays running continuously (higher resource use). If persistent: false, the background script is unloaded when idle and restarted on demand (for example, when you send a message from content script, popup, or an event triggers it).

Manifest V3 (chrome):

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "description": "Extension description",
  "permissions": [
    "storage",
    "tabs"
  ],

  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"]
  }]
}

that’s pretty much it,

thankyou soo much for reading 💛

PS: if you want to build & monetize your extension fast, you can checkout my boilerplate: extFast

bye bye :)

Local vs Sync vs Session: Which Chrome Extension Storage Should You Use?

Himanshu — Mon, 22 Dec 2025 06:43:34 +0000

Let's talk about storing data in browser extensions.

We have three options local storage, sync storage and session storage. Each one does something different, and picking the wrong one can lead to headaches down the road…

One quick thing, i created a complete chrome extension boilerplate that lets you ship & monetize your extension fast (includes auth, payments, and everything you need). It’s called extFast

Overview: Three Types of Extension Storage

Browser extensions have three primary storage APIs, each designed for specific use cases:

Local Storage (chrome.storage.local): Stores data locally on the user's device
Sync Storage (chrome.storage.sync): Syncs data across devices when the user is signed in
Session Storage (chrome.storage.session): Temporary storage that persists only during the browser session

Also these are different from the web's localStorage and sessionStorage APIs. Extension storage APIs work across all extension contexts (background scripts, content scripts, popups).

Chrome Storage Local: Device-Specific Storage

What is chrome.storage.local?

chrome.storage.local stores data locally on the user's machine. This data persists until explicitly deleted or the extension is uninstalled. It's ideal for storing large amounts of data that don't need to sync across devices.

Key Characteristics

Storage Limit: 10 MB (Chrome allows unlimited with unlimitedStorage permission)
Persistence: Survives browser restarts
Sync: Does NOT sync across devices
Browser Support: Chrome MV2 & MV3, Firefox MV2 & MV3
Best For: Cached data, large datasets, device-specific settings

Usage Example (Async/Await - Modern)

// Storing data
async function saveToLocal() {
  try {
    await chrome.storage.local.set({
      userPreferences: { theme: 'dark', fontSize: 16 },
      cachedData: [1, 2, 3, 4, 5]
    });
    console.log('Data saved to local storage');
  } catch (error) {
    console.error('Error saving to local storage:', error);
  }
}

// Retrieving data
async function getFromLocal() {
  try {
    const result = await chrome.storage.local.get(['userPreferences', 'cachedData']);
    console.log('User preferences:', result.userPreferences);
    console.log('Cached data:', result.cachedData);
    return result;
  } catch (error) {
    console.error('Error getting from local storage:', error);
  }
}

// Removing data
async function removeFromLocal() {
  try {
    await chrome.storage.local.remove(['cachedData']);
    console.log('Cached data removed');
  } catch (error) {
    console.error('Error removing from local storage:', error);
  }
}

// Clearing all data
async function clearLocal() {
  try {
    await chrome.storage.local.clear();
    console.log('All local storage cleared');
  } catch (error) {
    console.error('Error clearing local storage:', error);
  }
}

Usage Example (Promise-Based - Legacy)

// Storing data
function saveToLocal() {
  chrome.storage.local.set({
    userPreferences: { theme: 'dark', fontSize: 16 },
    cachedData: [1, 2, 3, 4, 5]
  })
  .then(() => {
    console.log('Data saved to local storage');
  })
  .catch((error) => {
    console.error('Error saving to local storage:', error);
  });
}

// Retrieving data
function getFromLocal() {
  chrome.storage.local.get(['userPreferences', 'cachedData'])
    .then((result) => {
      console.log('User preferences:', result.userPreferences);
      console.log('Cached data:', result.cachedData);
    })
    .catch((error) => {
      console.error('Error getting from local storage:', error);
    });
}

// Removing data
function removeFromLocal() {
  chrome.storage.local.remove(['cachedData'])
    .then(() => {
      console.log('Cached data removed');
    })
    .catch((error) => {
      console.error('Error removing from local storage:', error);
    });
}

Chrome Storage Sync: Cross-Device Synchronization

What is chrome.storage.sync?

chrome.storage.sync automatically syncs data across all devices where the user is signed into their browser account. This makes it perfect for user preferences and settings that should follow the user everywhere.

Key Characteristics

Storage Limit: 100 KB total, 8 KB per item
Persistence: Syncs across signed-in devices
Sync Frequency: Automatic when online
Browser Support: Chrome MV2 & MV3, Firefox MV2 & MV3
Best For: User settings, preferences, small configuration data

Usage Example (Async/Await - Modern)

// Storing data
async function saveToSync() {
  try {
    await chrome.storage.sync.set({
      theme: 'dark',
      language: 'en',
      notifications: true
    });
    console.log('Settings synced across devices');
  } catch (error) {
    console.error('Error saving to sync storage:', error);
  }
}

// Retrieving data
async function getFromSync() {
  try {
    const result = await chrome.storage.sync.get(['theme', 'language', 'notifications']);
    console.log('Theme:', result.theme);
    console.log('Language:', result.language);
    console.log('Notifications:', result.notifications);
    return result;
  } catch (error) {
    console.error('Error getting from sync storage:', error);
  }
}

Usage Example (Promise-Based - Legacy)

// Storing data
function saveToSync() {
  chrome.storage.sync.set({
    theme: 'dark',
    language: 'en',
    notifications: true
  })
  .then(() => {
    console.log('Settings synced across devices');
  })
  .catch((error) => {
    console.error('Error saving to sync storage:', error);
  });
}

// Retrieving data
function getFromSync() {
  chrome.storage.sync.get(['theme', 'language', 'notifications'])
    .then((result) => {
      console.log('Theme:', result.theme);
      console.log('Language:', result.language);
      console.log('Notifications:', result.notifications);
    })
    .catch((error) => {
      console.error('Error getting from sync storage:', error);
    });
}

Chrome Storage Session: Temporary Session Data

What is chrome.storage.session?

chrome.storage.session stores data in memory for the duration of the browser session. Data is cleared when the browser or extension is closed, making it perfect for temporary runtime state.

Key Characteristics

Storage Limit: 10 MB
Persistence: Only during browser session (cleared on browser close)
Browser Support:
- Chrome: Manifest V3 (Chrome 102+)
- Firefox: Both Manifest V2 and V3 supported
Access Control: By default, not exposed to content scripts (can be changed with setAccessLevel())
Best For: Temporary state, session-specific data, runtime variables

Usage Example (Async/Await - Modern)

// Storing session data
async function saveToSession() {
  try {
    await chrome.storage.session.set({
      currentTab: 'dashboard',
      isProcessing: false,
      temporaryToken: 'abc123xyz'
    });
    console.log('Session data stored');
  } catch (error) {
    console.error('Error saving to session storage:', error);
  }
}

// Retrieving session data
async function getFromSession() {
  try {
    const result = await chrome.storage.session.get(['currentTab', 'isProcessing']);
    console.log('Current tab:', result.currentTab);
    console.log('Is processing:', result.isProcessing);
    return result;
  } catch (error) {
    console.error('Error getting from session storage:', error);
  }
}

// Updating session data
async function updateSessionState() {
  try {
    await chrome.storage.session.set({ isProcessing: true });
    // Do some work...
    await chrome.storage.session.set({ isProcessing: false });
  } catch (error) {
    console.error('Error updating session storage:', error);
  }
}

// Setting access level (allows content scripts to access), call this function from background script (for example on extension installed)
async function enableContentScriptAccess() {
  try {
    await chrome.storage.session.setAccessLevel({
      accessLevel: 'TRUSTED_AND_UNTRUSTED_CONTEXTS'
    });
    console.log('Content scripts can now access session storage');
  } catch (error) {
    console.error('Error setting access level:', error);
  }
}

Usage Example (Promise-Based - Legacy)

// Storing session data
function saveToSession() {
  chrome.storage.session.set({
    currentTab: 'dashboard',
    isProcessing: false,
    temporaryToken: 'abc123xyz'
  })
  .then(() => {
    console.log('Session data stored');
  })
  .catch((error) => {
    console.error('Error saving to session storage:', error);
  });
}

// Retrieving session data
function getFromSession() {
  chrome.storage.session.get(['currentTab', 'isProcessing'])
    .then((result) => {
      console.log('Current tab:', result.currentTab);
      console.log('Is processing:', result.isProcessing);
    })
    .catch((error) => {
      console.error('Error getting from session storage:', error);
    });
}

Storage Comparison Table

Feature	Local Storage	Sync Storage	Session Storage
Storage Limit	10 MB (unlimited with permission)	100 KB	10 MB
Syncs Across Devices	No	Yes	No
Persistence	Until deleted	Until deleted	Session only
Chrome Support	MV2 & MV3	MV2 & MV3	MV3
Firefox Support	MV2 & MV3	MV2 & MV3	MV2 & MV3
Best Use Case	Large data, cache	User preferences	Temporary state
Speed	Fast	Slower (sync overhead)	Fast (in-memory)

Chrome vs Firefox: Key Differences

Browser Namespace Compatibility

Both Chrome and Firefox support similar storage APIs, but Firefox uses a different namespace:

// Chrome (and Chromium-based browsers)
chrome.storage.local.set({ key: 'value' });

// Firefox supports both namespaces
browser.storage.local.set({ key: 'value' }); // Preferred in Firefox
chrome.storage.local.set({ key: 'value' });   // Also works in Firefox

// Cross-browser compatible approach
const storageAPI = typeof browser !== 'undefined' ? browser : chrome;
await storageAPI.storage.local.set({ key: 'value' });

Manifest Configuration Examples

Firefox Manifest V2:

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"], 👈
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  }
}

Chrome Manifest V3:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"], 👈
  "background": {
    "service_worker": "background.js"
  }
}

Firefox Manifest V3:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "permissions": ["storage"], 👈
  "background": {
    "scripts": ["background.js"]
  }
}

source

Listening to Storage Changes

Monitor storage changes across all extension contexts:

Async/Await Example

// Listen to all storage areas
chrome.storage.onChanged.addListener((changes, areaName) => {
  console.log(`Storage area '${areaName}' changed`);

  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(`Key '${key}' changed from`, oldValue, 'to', newValue);
  }
});

// Listen to specific storage area
chrome.storage.session.onChanged.addListener((changes) => {
  if (changes.isProcessing) {
    console.log('Processing state changed:', changes.isProcessing.newValue);
  }
});

// Firefox-specific listener using browser namespace
if (typeof browser !== 'undefined') {
  browser.storage.session.onChanged.addListener((changes) => {
    console.log('Session storage changed (Firefox):', changes);
  });
}

2. Handle Storage Quota

async function checkStorageQuota() {
  try {
    // Check local storage quota
    const localBytes = await chrome.storage.local.getBytesInUse();
    console.log(`Local storage using ${localBytes} bytes`);

    // Check session storage quota
    if (chrome.storage.session) {
      const sessionBytes = await chrome.storage.session.getBytesInUse();
      console.log(`Session storage using ${sessionBytes} bytes`);
    }
  } catch (error) {
    console.error('Error checking quota:', error);
  }
}

yeah pretty much done now!

PS: if you want to build & monetize your extension fast, you can checkout my chrome extension boilerplate: extFast

thankyou soo much for reading 💛

bye bye :)

How to integrate Lemon Squeezy Payments into a chrome extension with webhooks

Himanshu — Tue, 16 Dec 2025 17:55:07 +0000

I’ll show how i implement Lemon Squeezy monthly subscription and one-time payment in my browser extension. and how I handle Lemon Squeezy payment webhook events.

Quick note: this code comes from my extension boilerplate, extFast. if you wanna skip adding subscriptions, auth, feedback form, landing page & 1 billion other boring stuff, clone it here

or let's code it…

TL;DR

User clicks "Upgrade to Premium" in your extension popup
Extension calls your serverless function to create a checkout link
Serverless function communicates with Lemon Squeezy API
Your background script redirect user to Lemon Squeezy checkout page (email pre-filled)
After successful payment, Lemon Squeezy sends webhook to your server
Webhook handler stores subscription data in your database
Done.

Part 1: Setting Up Lemon Squeezy

Step 1: Create Your Lemon Squeezy Account

Visit https://www.lemonsqueezy.com/ and sign up for a test account
Complete the onboarding process

Step 2: Create Your Product

Navigate to Products in your dashboard
Click New Product
Create a subscription product (e.g., "Premium Plan - Monthly")
Set your pricing (e.g., $9.99/month)
After creating the product, click on it to view details
Important: Copy the Variant ID (not the Product ID)
- The Variant ID looks like: 123456
- You'll need this for creating checkout links in you chrome extension

Step 3: Generate API Key

Go to Settings → API
Click Create API Key
Give it a name (e.g., "Chrome Extension API")
Copy the API key immediately (you won't see it again)

Step 4: Get Your Store ID

Go to Settings → Stores
You'll see your store with a number like #123456
Copy only the numbers (without the # symbol)

Step 5: Create Webhook Secret

Unlike some payment processors, Lemon Squeezy don't really give you the webhook secret token, so you need to type/create a random string in .env file.

Step 6: Configure Environment Variables

Create a .env.local file in your Next.js project:

LEMONSQUEEZY_API_KEY=your_api_key_here
LEMONSQUEEZY_STORE_ID=123456
LEMONSQUEEZY_WEBHOOK_SECRET=your_handmade_secret_token   # just type any random string
NEXT_PUBLIC_CHECKOUT_SUCCESS_URL=https://yourapp.com/checkout-success

Important Notes:

Use the Variant ID, not the Product ID
NEXT_PUBLIC_CHECKOUT_SUCCESS_URL is where users land after payment (optional)
Keep the LEMONSQUEEZY_API_KEY and WEBHOOK_SECRET secure (never in client code)

Part 2: Setting Up Your Backend (Serverless Functions)

We'll create two serverless functions (pretty much free, if you are hosting on vercel):

Generate checkout links
Handle webhook events

Step 1: Install Dependencies

npm install @lemonsqueezy/lemonsqueezy.js

(i wrote the code in typescript [bcz people use ts in production] but if you are a js human, you can easily convert it into javascript, just copy paste it in claude or something :)

Step 2: Create Lemon Squeezy Client

Create lib/lemonSqueezy/lemonSqueezyClient.ts:

import { lemonSqueezySetup } from "@lemonsqueezy/lemonsqueezy.js";

export function configureLemonSqueezy() {
  lemonSqueezySetup({
    apiKey: process.env.LEMONSQUEEZY_API_KEY!,
    onError: (error) => {
      console.error("Lemon Squeezy Error:", error);
      throw error;
    },
  });
}

Step 3: Create Checkout API Endpoint

Create app/api/checkout/route.ts:

import { createCheckout } from "@lemonsqueezy/lemonsqueezy.js";
import { configureLemonSqueezy } from "@/lib/lemonSqueezy/lemonSqueezyClient";

async function createCheckoutLS(
  productId: string,
  userEmail?: string
) {
  configureLemonSqueezy();

  const storeId = process.env.LEMONSQUEEZY_STORE_ID;

  if (!storeId) {
    throw new Error("LEMONSQUEEZY_STORE_ID is not set");
  }

  const checkoutData = {
    productOptions: {
      redirectUrl: process.env.NEXT_PUBLIC_CHECKOUT_SUCCESS_URL,
    },
    checkoutData: {
      email: userEmail || undefined,
    },
  };

  const checkout = await createCheckout(
    storeId,
    productId,
    checkoutData
  );

  if (checkout.error) {
    throw new Error(checkout.error.message);
  }

  return checkout.data?.data.attributes.url;
}

export async function POST(request: Request) {
  try {
    const { productId, userEmail } = await request.json();

    if (!productId) {
      return new Response(
        JSON.stringify({ error: 'Product variant ID is required' }),
        {
          status: 400,
          headers: { 'Content-Type': 'application/json' },
        }
      );
    }

    const checkoutUrl = await createCheckoutLS(
      productId,
      userEmail || undefined
    );

    return new Response(
      JSON.stringify({ checkout_url: checkoutUrl }),
      {
        status: 201,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  } catch (error) {
    console.error('Checkout creation error:', error);
    return new Response(
      JSON.stringify({
        error: 'Failed to create checkout',
        details: error instanceof Error ? error.message : 'Unknown error'
      }),
      {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  }
}

What this does:

Accepts POST requests with productId and optional userEmail
Creates a personalized checkout link via Lemon Squeezy API
Pre-fills the user's email on the checkout page (better UX)
Returns the checkout URL to your extension

Part 3: Building Your Chrome Extension

Step 1: Create Checkout Handler

Create src/handleCheckout.ts in your extension:

/**
 * Creates a checkout URL by calling your serverless function
 * @param email - User's email to pre-fill at checkout
 * @param productId - Lemon Squeezy variant ID
 * @returns Checkout URL or null if failed
 */
export async function createCheckoutURL(
  email: string | null,
  productId: string
): Promise<string | null> {
  const CHECKOUT_ENDPOINT = 'https://your-app.vercel.app/api/checkout';

  try {
    const response = await fetch(CHECKOUT_ENDPOINT, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        productId,
        userEmail: email,
      }),
    });

    if (!response.ok) {
      console.error('Checkout creation failed:', response.statusText);
      return null;
    }

    const results = await response.json();
    return results.checkout_url;
  } catch (error) {
    console.error('Error creating checkout URL:', error);
    return null;
  }
}

/**
 * Initiates checkout flow by sending message to background script
 * @param email - User's email
 * @param productId - Product variant ID to purchase
 */
export async function invokeCheckout(email?: string, productId?: string) {
  await chrome.runtime.sendMessage({
    type: 'checkout',
    userEmail: email,
    productId: productId || import.meta.env.WXT_LEMONSQUEEZY_PRODUCT_ID,
  });
}

# .env.local (your extension, not serverless function)

WXT_LEMONSQUEEZY_PRODUCT_ID=your_variant_id_here  # pro plan

Step 2: Set Up Background Script

Create or update src/background.ts:

import { createCheckoutURL } from './lib/handleCheckout';

type CheckoutMessage = {
  type: 'checkout';
  userEmail?: string;
  productId: string;
};

async function handleMessages(
  message: CheckoutMessage,
  sender: chrome.runtime.MessageSender,
  sendResponse: (response?: any) => void
) {
  if (message.type === 'checkout') {
    console.log('🛒 Starting checkout flow...');

    // Generate the checkout link
   // productId is coming from invokeCheckout <- popup.tsx

    const checkoutLink = await createCheckoutURL(
      message.userEmail || null,
      message.productId
    );

    if (!checkoutLink) {
      console.error('❌ Failed to create checkout link');
      sendResponse({ success: false, error: 'Failed to create checkout' });
      return;
    }

    // Redirect user to checkout page (no manifest permission needed)
    chrome.tabs.create({ url: checkoutLink }, (tab) => {
      console.log('✅ Redirected to checkout:', checkoutLink);
      sendResponse({ success: true, tabId: tab.id });
    });
  }
}

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  handleMessages(request, sender, sendResponse);
  return true; // Required for async sendResponse
});

How it works:

Listens for 'checkout' messages from popup or content scripts
Calls your serverless function to generate checkout URL
Opens new tab with the checkout page
No manifest permissions needed for opening tabs

Step 3: Create Premium Upgrade UI

Create a component in your popup (src/components/PremiumCard.tsx):

import React from 'react';
import { invokeCheckout } from '../lib/handleCheckout';

export default function PremiumCard() {

  async function handleUpgradeClick() {
    try {
    // Get user's email from your auth system or chrome.storage
      await invokeCheckout('example@gmail.com');
    } catch (error) {
      console.error('Checkout error:', error);

    } 
  }

  return (
    <div className="premium-card">
      <div className="premium-header">
        <h3>🚀 Upgrade to Premium</h3>
        <p className="price">$9.99/month</p>
      </div>

      <ul className="features">
        <li>✨ Unlimited AI generations</li>
        <li>🎯 Advanced features</li>
        <li>⚡ Priority support</li>
        <li>🔒 Ad-free experience</li>
      </ul>

      <button
        onClick={handleUpgradeClick}
        className="upgrade-button"
      >
        {'Get Premium Now'}
      </button>
    </div>
  );
}

User Flow:

User clicks "Get Premium Now"
Message sent to background script
Checkout URL generated with pre-filled email
User redirected to Lemon Squeezy checkout
User completes payment
User redirected to success page (optional)

Part 4: Database Setup (Supabase)

Step 1: Create Supabase Table

Run this SQL in your Supabase SQL Editor:

CREATE TABLE PremiumUsers (
  user_email TEXT PRIMARY KEY,
  subscription_status TEXT NOT NULL,
  plan_type TEXT,
  credits_used INTEGER DEFAULT 0,
  subscribed_at TIMESTAMPTZ,
  expires_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  subscription_id TEXT,
  customer_id TEXT
);

-- Add index for faster queries
CREATE INDEX idx_subscription_status ON PremiumUsers(subscription_status);
CREATE INDEX idx_expires_at ON PremiumUsers(expires_at);

Step 2: Set Up Supabase Client

Create lib/supabase/supabaseAdmin.ts:

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY!;

// Use service role key for admin operations
const supabaseAdmin = createClient(supabaseUrl, supabaseServiceKey);

export default supabaseAdmin;

Add to .env.local:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Part 5: (now the most scary part) Webhooks

but they are important to store your premium users into your database and keep it in sync with lemon squeezy

Step 1: Create Type Definitions (optional)

Create app/api/webhooks/lemon-squeezy/types.ts:

export interface LemonSqueezyWebhookPayload {
  meta: {
    event_name: string;
    custom_data?: Record<string, any>;
  };
  data: {
    id: string;
    attributes: {
      user_email: string;
      status: string;
      variant_name: string;
      created_at: string;
      renews_at: string | null;
      ends_at: string | null;
      customer_id: number;
    };
  };
}

Step 2: Create Webhook Endpoint

Create app/api/webhooks/lemon-squeezy/route.ts:

import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
import supabaseAdmin from "@/lib/supabase/supabaseAdmin";
import type { LemonSqueezyWebhookPayload } from "./types";

// Verify webhook signature to ensure it's from Lemon Squeezy
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const hmac = crypto.createHmac("sha256", secret);
  const digest = hmac.update(payload).digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Map Lemon Squeezy status to our internal status

function mapSubscriptionStatus(status: string): string {
  const statusMap: Record<string, string> = {
    active: "active",
    on_trial: "trialing",
    paused: "paused",
    past_due: "past_due",
    unpaid: "unpaid",
    cancelled: "cancelled",
    expired: "expired",
  };
  return statusMap[status] || status;
}

/// Determine plan type from variant name

function determinePlanType(
  variantName: string,
  customData?: Record<string, any>
): string {
  if (customData?.plan) {
    return customData.plan;
  }

  const lowerVariantName = variantName.toLowerCase();
  if (lowerVariantName.includes("yearly") || lowerVariantName.includes("annual")) {
    return "yearly";
  }
  return "monthly";
}

// Handle subscription creation, update, and cancellation

async function handleSubscriptionChange(payload: LemonSqueezyWebhookPayload) {
  console.log("📦 Processing webhook:", {
    event: payload.meta.event_name,
    email: payload.data.attributes.user_email,
    status: payload.data.attributes.status,
  });

  const attributes = payload.data.attributes;
  const planType = determinePlanType(
    attributes.variant_name,
    payload.meta.custom_data
  );

  const { error } = await supabaseAdmin
    .from("PremiumUsers")
    .upsert(
      {
        user_email: attributes.user_email,
        subscription_status: mapSubscriptionStatus(attributes.status),
        subscribed_at: new Date(attributes.created_at).toISOString(),
        expires_at: attributes.renews_at
          ? new Date(attributes.renews_at).toISOString()
          : attributes.ends_at
          ? new Date(attributes.ends_at).toISOString()
          : null,
        subscription_id: payload.data.id,
        customer_id: attributes.customer_id.toString(),
        plan_type: planType,
      },
      { onConflict: "user_email" }
    );

  if (error) {
    console.error("❌ Database update failed:", error);
    throw error;
  }

  console.log("✅ Updated subscription for:", attributes.user_email);
}

export async function POST(request: NextRequest) {
  try {
    const webhookSecret = process.env.LEMONSQUEEZY_WEBHOOK_SECRET;

    if (!webhookSecret) {
      console.error("❌ LEMONSQUEEZY_WEBHOOK_SECRET is not set");
      return NextResponse.json(
        { error: "Webhook secret not configured" },
        { status: 500 }
      );
    }

    // Get raw body for signature verification
    const rawBody = await request.text();
    const signature = request.headers.get("x-signature");

    if (!signature) {
      console.error("❌ No signature in webhook request");
      return NextResponse.json(
        { error: "No signature provided" },
        { status: 401 }
      );
    }

    // Verify the webhook is from Lemon Squeezy
    const isValid = verifyWebhookSignature(rawBody, signature, webhookSecret);

    if (!isValid) {
      console.error("❌ Invalid webhook signature");
      return NextResponse.json(
        { error: "Invalid signature" },
        { status: 401 }
      );
    }

    // Parse and process the webhook
    const payload: LemonSqueezyWebhookPayload = JSON.parse(rawBody);
    const eventName = payload.meta.event_name;

    console.log(`🔔 Webhook event: ${eventName}`);

    // Handle different subscription events (you can remove some of them actually)
    // i think all you need it "subscription_updated" and "subscription_created"
    switch (eventName) {
      case "subscription_created":
      case "subscription_updated":
      case "subscription_resumed":
      case "subscription_unpaused":
        await handleSubscriptionChange(payload);
        break;

      case "subscription_cancelled":
      case "subscription_expired":
      case "subscription_paused":
        await handleSubscriptionChange(payload);
        break;

      case "order_created":
        console.log("📦 One-time order:", payload.data.attributes.user_email);
        // Handle one-time purchases if needed
        break;

      default:
        console.log(`ℹ️ Unhandled event: ${eventName}`);
    }

    return NextResponse.json({ received: true });
  } catch (error) {
    console.error("❌ Webhook processing error:", error);
    return NextResponse.json(
      {
        error: "Webhook processing failed",
        details: error instanceof Error ? error.message : "Unknown error"
      },
      { status: 500 }
    );
  }
}

this is how the webhook payload/object looks like for subscription_created event that lemon squeezy sent you:

{
  "data": {
    "id": "xxxxxx",
    "type": "subscriptions",
    "links": {
      "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx"
    },
    "attributes": {
      "urls": {
        "customer_portal": "https://extfast.lemonsqueezy.com/billing?xxxxxx",
        "update_payment_method": "https://extfast.lemonsqueezy.com/subscription/xxxxxx",
        "customer_portal_update_subscription": "https://extfast.lemonsqueezy.com/billing/xxxxxxx"
      },
      "pause": null,
      "status": "active",
      "ends_at": null,
      "order_id": xxxxx,
      "store_id": xxxxxx,
      "cancelled": false,
      "renews_at": "2026-01-16T13:43:48.000000Z",
      "test_mode": true,
      "user_name": "banana man",
      "card_brand": "visa",
      "created_at": "2025-12-16T13:43:50.000000Z",
      "product_id": xxxxx,
      "updated_at": "2025-12-16T13:44:01.000000Z",
      "user_email": "banana-man@extfast.com",
      "variant_id": xxxxx,
      "customer_id": xxxxxx,
      "product_name": "Demo Subscription Product",
      "variant_name": "Default",
      "order_item_id": xxxxx,
      "trial_ends_at": null,
      "billing_anchor": 16,
      "card_last_four": "4242",
      "status_formatted": "Active",
      "payment_processor": "stripe",
      "first_subscription_item": {
        "id": xxxxx,
        "price_id": xxxxx,
        "quantity": 1,
        "created_at": "2025-12-16T13:44:02.000000Z",
        "updated_at": "2025-12-16T13:44:02.000000Z",
        "is_usage_based": false,
        "subscription_id": xxxxx
      }
    },
    "relationships": {
      "order": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/relationships/order",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/order"
        }
      },
      "store": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/relationships/store",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/store"
        }
      },
      "product": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/relationships/product",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxxxx/product"
        }
      },
      "variant": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/relationships/variant",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/variant"
        }
      },
      "customer": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/hahahahah/relationships/customer",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/hahahahah/customer"
        }
      },
      "order-item": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxxx/relationships/order-item",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxxx/order-item"
        }
      },
      "subscription-items": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/relationships/subscription-items",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxx/subscription-items"
        }
      },
      "subscription-invoices": {
        "links": {
          "self": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxxx/relationships/subscription-invoices",
          "related": "https://api.lemonsqueezy.com/v1/subscriptions/xxxxxx/subscription-invoices"
        }
      }
    }
  },
  "meta": {
    "test_mode": true,
    "event_name": "subscription_created",
    "webhook_id": "xxxxxxxx-xxxxx-xxxxx"
  }
}

now to test this webhook function api/webhooks/lemon-squeezy, you need to install ngrok on you machine and create a tunnel (localhost:3000 url is not gonna work here) or simply deploy it on vercel and then test it (little bit painful i know)

Step 3: Configure Webhook in Lemon Squeezy

Deploy your function to Vercel first
Go to Lemon Squeezy Dashboard → Settings → Webhooks
Click + to add a new webhook
Set URL: https://your-app.vercel.app/api/webhooks/lemon-squeezy
Paste your webhook secret (the one you created in your .env file)
Select events to listen for:
- subscription_created
- subscription_updated
- subscription_cancelled
- subscription_resumed
- subscription_paused
- subscription_expired
Click Save

Part 6: Verifying Premium User (optional)

In Your Serverless Functions

Create app/api/premium-feature/route.ts:

import supabaseAdmin from '@/lib/supabase/supabaseAdmin';

async function isEligibleUser(userEmail: string): Promise<boolean> {
  try {
    const { data, error } = await supabaseAdmin
      .from('PremiumUsers')
      .select('subscription_status, expires_at')
      .eq('user_email', userEmail)
      .single();

    if (error) {
      console.error('Premium check error:', error);
      return false;
    }

    if (!data) {
      return false;
    }

    const status = data.subscription_status.trim().toLowerCase();
    const isPremiumActive = status === 'active' || status === 'trialing';

    // Also check if subscription hasn't expired
    if (data.expires_at) {
      const expiresAt = new Date(data.expires_at);
      const now = new Date();
      if (now > expiresAt) {
        return false;
      }
    }

    return isPremiumActive;
  } catch (error) {
    console.error('Premium eligibility check failed:', error);
    return false;
  }
}

export async function POST(request: Request) {
  try {
    const { userEmail, action } = await request.json();

    if (!userEmail) {
      return Response.json(
        { error: 'User email required' },
        { status: 400 }
      );
    }

    const isEligible = await isEligibleUser(userEmail);

    if (!isEligible) {
      return Response.json(
        { error: 'Premium subscription required' },
        { status: 403 }
      );
    }

    // User is premium, proceed with premium feature
    // Your premium feature logic here...

    return Response.json({
      success: true,
      message: 'Premium feature executed'
    });
  } catch (error) {
    console.error('API error:', error);
    return Response.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

phew!

you_done_now

btw i assumed that you already implemented authentication (like Continue With Google) in your extension before adding stripe payments.

If you don’t know how to add google auth → checkout my boilerplate

thankyou so much for reading 💛

have a nice day

bye bye :)

How to Create Offscreen Documents in Chrome Extensions: A Complete Guide

Himanshu — Mon, 15 Dec 2025 13:40:45 +0000

If you're building Chrome extensions with Manifest V3, you've likely encountered the challenge of service workers dying frequently. This is where offscreen documents come to the rescue. In this comprehensive guide, we'll explore what offscreen documents are, where they live, and how to implement them in your Chrome extension.

What is an Offscreen Document?

An offscreen document is a hidden HTML document that runs in the background of your Chrome extension. Unlike service workers that terminate quickly to save resources, offscreen documents can maintain persistent state and perform continuous operations without being visible to the user.

Think of it as an invisible webpage that your extension controls, providing a stable environment for long-running tasks that would otherwise be interrupted by service worker lifecycle limitations.

When Should You Use Offscreen Documents?

Offscreen documents are ideal for several scenarios:

Persistent Data Processing: When you need to maintain data structures like Map() or Set() objects that would be lost when service workers terminate
Heavy Computations: Processing large datasets or performing complex calculations that need consistent access to memory
Audio/Video Processing: Handling media that requires continuous operation

Important Limitations:

Offscreen documents cannot access the host website's DOM elements (like buttons or content)
also they're only available in Manifest V3 (Chrome extensions only, not Firefox)
they run in an isolated context separate from your content scripts
they can only access one chrome api which is chrome.runtime for messaging, they can't access storage or tabs api

Step 1: Add Offscreen Permission to manifest.json

First, declare the offscreen permission in your manifest file:

{
  "manifest_version": 3,
  "name": "Your billion dollar Extension Name",
  "version": "1.0.0",
  "description": "a really not so long extension description here",

  "permissions": ["offscreen"],

  "background": {
    "service_worker": "background.js",
    "type": "module"
  },

}

The "offscreen" permission is important and must be explicitly declared for your extension to create offscreen documents.

Step 2: Create the Offscreen HTML File

Create an offscreen.html file in your extension's root directory:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Offscreen Document</title>
</head>
<body>
    <!-- This document runs invisibly in the background -->
</body>
<script type="module" src="offscreen.js"></script>
</html>

This HTML file serves as the entry point for your offscreen document. It's never displayed to users but provides the execution environment (this is some chrome’s stupidity, it’s purely useless but necessary)

Step 3: Create the Offscreen JavaScript File

Create offscreen.js where you'll handle your persistent operations:

// Perform heavy processing or maintain persistent state
console.log('hey human!, your offscreen document is live');

// Listen for messages from the background script or content script
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'Blah_Blah') {
    // Perform your processing here

  }
  return true; // Keep the message channel open for async response
});

btw Your offscreen console logs will appear in the same inspector as your service worker. Navigate to chrome://extensions/, enable Developer mode, and click the "service worker" link.

Step 4: initializing Offscreen Document from Background Script

The most important part, create the offscreen document from your background script (background.js):

let creatingOffscreen = null;

async function ensureOffscreen() {
  const offscreenUrl = chrome.runtime.getURL('offscreen.html');

  // Check if offscreen document already exists
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [offscreenUrl],
    });

    if (contexts.length > 0) {
      console.log('Offscreen document already exists');
      return;
    }
  } else {
    // Fallback for older Chrome versions
    const clients = await self.clients.matchAll();
    if (clients.some((client) => client.url.includes(chrome.runtime.id))) {
      return;
    }
  }

  // Create offscreen document
  // put a good looking 'justification' here because they will review it
  if (!creatingOffscreen) {
    creatingOffscreen = chrome.offscreen.createDocument({
      url: 'offscreen.html',
      reasons: ['WORKERS'],
      justification: 'Maintain persistent data structures for extension functionality',

    });

    await creatingOffscreen;
    creatingOffscreen = null;
    console.log('Offscreen document created successfully');
  } else {
    await creatingOffscreen;
  }
}

// Create offscreen on browser startup
chrome.runtime.onStartup.addListener(() => {
  ensureOffscreen();
  console.log('Extension started, offscreen document ensured');
});

// Create offscreen on extension installation
chrome.runtime.onInstalled.addListener(() => {
  ensureOffscreen();
  console.log('Extension installed, offscreen document created');
});

// Handle messages (from content script) to ensure offscreen exists
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg && msg.type === 'ensure_offscreen') {
    ensureOffscreen()
      .then(() => sendResponse({ ok: true }))
      .catch((err) => sendResponse({ ok: false, error: String(err) }));
    return true;
  }
});

The `ensureOffscreen()` Function:

This function implements a pattern:

Check if offscreen exists: Uses chrome.runtime.getContexts() (preferred) or self.clients.matchAll() (fallback) to check for existing offscreen documents
Prevent duplicate creation: Uses a creatingOffscreen promise to prevent race conditions
Create if needed: Only creates a new offscreen document if one doesn't exist

Required Parameters for createDocument()

When creating an offscreen document, keep these things in mind:

url: The path to your offscreen HTML file
reasons: An array of valid reasons from the Chrome API documentation. Valid reasons include:
- AUDIO_PLAYBACK
- BLOBS
- CLIPBOARD
- DOM_PARSER
- DOM_SCRAPING
- IFRAME_SCRIPTING
- LOCAL_STORAGE
- TESTING
- WORKERS
- etc
justification: A clear explanation of why you need the offscreen document. This is reviewed by the Chrome team during the extension review process.

Closing Offscreen Documents

When you no longer need the offscreen document, close it to free up resources, though i never tried this code, because i never closed it, but i think it will work, but check it yourself pls:

async function closeOffscreen() {
  try {
    await chrome.offscreen.closeDocument();
    console.log('Offscreen document closed');
  } catch (error) {
    console.error('Error closing offscreen document:', error);
  }
}

See the official documentation for more details.

Communication Between Background and Offscreen

Use Chrome's messaging API to communicate between your background script and offscreen document:

From background to offscreen:

chrome.runtime.sendMessage({
  type: 'Blah_Blah',
}, (response) => {
  console.log('Response from offscreen:', response);
});

Important

Browser Support: Offscreen documents are Manifest V3 only meaning you can only use offscreen document in chrome and other chromium based browser and it is not available for Firefox extensions (manifest version 2)
DOM Access: offscreen cannot access the host website's DOM elements, you need to transfer a lot of info via messaging
Persistence: Unlike service workers, offscreen documents can maintain state between operations (most cool thing)
Visibility: Completely hidden from users, no UI elements

btw i created a chrome extension boilerplate that contains auth, subscription, forget password, contact form and everything you need to build and monetize extension fast, you can check it out here: extFast

thank you sooo much for reading 💛

have a nice day,

bye bye :)

How to integrate Stripe Payments into a chrome extension (step by step)

Himanshu — Sun, 14 Dec 2025 08:05:54 +0000

Here’s how i implement stripe monthly subscription and one-time payment in my browser extension. I will also show you how i handle stripe webhook events.

Quick note: this code comes from my extension boilerplate, extFast. if you wanna skip implementing subscriptions, auth, feedback form, landing page and 1 billion other boring stuff, clone it here

or let's code it….

Overview

Here's how the payment flow works:

User clicks "Upgrade to Premium" in your extension popup
Extension calls your serverless function to generate a Stripe checkout URL
Background script redirects user to the Stripe checkout page
User completes payment on Stripe's secure checkout
Stripe sends a webhook to your serverless function
Your webhook handler saves the subscription data to your database
Extension verifies premium status when user tries to access premium features

Part 1: Setting Up Stripe

Step 1: Create a Stripe Sandbox Account

For development and testing, start with a Stripe sandbox:

Visit Stripe Sandbox Documentation
Create a new sandbox account

Step 2: Create Your Product

Go to Products in your Stripe dashboard
Click Add Product
Enter product details:
- Name: "Premium Subscription"
- Description: "Monthly premium access"
- Pricing: $9.99/month (or your chosen price)
Copy the Price ID (starts with price_) - you'll need this later

Step 3: Get Your API Keys

Navigate to Developers → API Keys or visit this link
Copy your Secret Key (starts with sk_test_ for sandbox)
Store this securely - never commit it to your repository

Reference: Stripe API Keys Documentation

Part 2: Creating Serverless Functions

We'll create two serverless functions:

Generate checkout URLs
Handle Stripe webhooks

Setting Up Your Project

First, install the Stripe SDK:

npm install stripe --save

Reference: Stripe SDK Docs

i wrote the code in typescript but you can easily convert it into javascript, just use claude or something.

Initialize Stripe Client

Create a file to initialize your Stripe client:

// lib/stripe/stripeClient.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2025-11-17.clover',
  typescript: true,
});

export default stripe;

STRIPE_SECRET_KEY is coming from .env i am very sure you already know how to put keys in env file

Function 1: Create Checkout Links

This serverless function generates personalized checkout URLs with the user's email pre-filled:

// app/api/checkout/route.ts

import stripe from '@/lib/stripe/stripeClient';

/// typescript stuff (ignore it)
interface CreateCheckoutParams {
  user?: {
    customerId?: string;
    email?: string;
  };
  mode: 'payment' | 'subscription';
  clientReferenceId?: string;
  priceId: string;
  couponId?: string | null;
}

export const createCheckoutStripe = async ({
  user,
  mode,
  clientReferenceId,
  priceId,
  couponId,
}: CreateCheckoutParams): Promise<string | null> => {
  try {
    const extraParams: {
      customer?: string;
      customer_creation?: 'always';
      customer_email?: string;
      invoice_creation?: { enabled: boolean };
      payment_intent_data?: { setup_future_usage: 'on_session' };
      tax_id_collection?: { enabled: boolean };
    } = {};

    // Handle existing customers vs new customers
    if (user?.customerId) {
      extraParams.customer = user.customerId;
    } else {
      if (mode === 'payment') {
        extraParams.customer_creation = 'always';
        extraParams.invoice_creation = { enabled: true };
        extraParams.payment_intent_data = { setup_future_usage: 'on_session' };
      }
      if (user?.email) {
        extraParams.customer_email = user.email;
      }
      extraParams.tax_id_collection = { enabled: true };
    }

    const stripeSession = await stripe.checkout.sessions.create({
      mode,
      allow_promotion_codes: true,
      client_reference_id: clientReferenceId,
      line_items: [
        {
          price: priceId,
          quantity: 1,
        },
      ],
      discounts: couponId
        ? [
            {
              coupon: couponId,
            },
          ]
        : [],
      success_url: 'https://example.com/checkout-success',
      cancel_url: 'https://example.com/home',
      locale: 'auto',
      ...extraParams,
    });

    return stripeSession.url;
  } catch (e) {
    console.error('Error creating checkout session:', e);
    return null;
  }
};

export async function POST(request: Request) {
  try {
    const { id, userEmail, mode } = await request.json();

    // Validation
    if (!id) {
      return new Response(JSON.stringify({ error: 'Price ID is missing' }), {
        status: 400,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    if (!mode) {
      return new Response(
        JSON.stringify({
          error: "Mode is missing (choose 'payment' or 'subscription')",
        }),
        {
          status: 400,
          headers: { 'Content-Type': 'application/json' },
        }
      );
    }

    const checkoutUrl = await createCheckoutStripe({
      user: {
        email: userEmail,
      },
      mode,
      priceId: id,
    });

    if (!checkoutUrl) {
      return new Response(JSON.stringify({ error: 'Failed to create url' }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    return new Response(JSON.stringify({ checkout_url: checkoutUrl }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    console.error('Checkout error:', error);
    return new Response(JSON.stringify({ error: 'Internal server error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}

Alternative Approach: If you don't need to pre-fill the user's email, you can generate a fixed checkout link directly from the Stripe dashboard (Products → Checkout Links) and skip this function entirely.

Part 3: Building the Chrome Extension

Extension File Structure

your-extension/
├── manifest.json
├── popup/
│   ├── popup.html
│   └── popup.tsx
├── background/
│   └── background.ts
├── utils/
│   └── handleCheckout.ts
└── components/
    └── PremiumCard.tsx

Step 1: Checkout Handler

Create a utility file to handle checkout operations:

// utils/handleCheckout.ts

/**
 * Generates a Stripe checkout URL by calling your serverless function
 * This pre-fills the user's email on the checkout page
 */
export async function createCheckoutURL(
  email: string | null,
  priceId: string,
  mode: 'payment' | 'subscription' = 'subscription'
): Promise<string | null> {
  // Replace with your actual Vercel endpoint
  const CHECKOUT_ENDPOINT = 'https://your-app.vercel.app/api/checkout';

  try {
    const response = await fetch(CHECKOUT_ENDPOINT, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        id: priceId,
        userEmail: email || null,
        mode: mode,
      }),
    });

    if (!response.ok) {
      console.error('Failed to create checkout URL:', response.statusText);
      return null;
    }

    const results = await response.json();
    return results.checkout_url;
  } catch (error) {
    console.error('Error creating checkout URL:', error);
    return null;
  }
}

/**
 * Initiates the checkout flow by sending a message to the background script
 * Call this function when the user clicks "Upgrade to Premium"
 */
export async function invokeCheckout(
  email: string | undefined,
  priceId: string
): Promise<void> {
  try {
    await chrome.runtime.sendMessage({
      type: 'checkout',
      userEmail: email,
      priceId: priceId,
    });
  } catch (error) {
    console.error('Error invoking checkout:', error);
  }
}

Step 2: Background Script

The background script handles messages and redirects users to checkout:

// background/background.ts

import { createCheckoutURL } from '../utils/handleCheckout';

/// some typescript stuff (ignore it)
type CheckoutMessage = {
  type: 'checkout';
  userEmail?: string;
  priceId: string;
};

async function handleMessages(
  message: CheckoutMessage,
  sender: chrome.runtime.MessageSender,
  sendResponse: (response?: any) => void
) {
  if (message.type === 'checkout') {
    try {
      console.log('🚀 Starting checkout process...');

      // Generate the checkout link
      // passing the string 'subscription' or 'payment' is important
      const checkoutLink = await createCheckoutURL(
        message.userEmail || null,
        message.priceId,
        'subscription'
      );

      if (!checkoutLink) {
        console.error('❌ Failed to create checkout link');
        return;
      }

      console.log('✅ Checkout link created successfully');

      // Redirect user to Stripe checkout (no manifest permission needed)
      chrome.tabs.create({ url: checkoutLink }, function (tab) {
        console.log('📄 Opened checkout page:', checkoutLink);
      });
    } catch (error) {
      console.error('❌ Error in checkout flow:', error);
    }
  }
}

// Listen for messages from popup or content scripts
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  handleMessages(request, sender, sendResponse);
  return true; // Keep the message channel open for async responses
});

Step 3: “Upgrade Card” Component

Let’s create premium upgrade card widget for your popup:

// components/PremiumCard.tsx

import React from 'react';
import { invokeCheckout } from '../utils/handleCheckout';

interface PremiumCardProps {
  userEmail?: string;
}

export default function PremiumCard({ userEmail }: PremiumCardProps) {
  // Replace with your actual Stripe Price ID
  const PRICE_ID = 'price_1234567890abcdef';

  async function handleUpgradeClick() {
    try {
      await invokeCheckout(userEmail, PRICE_ID);
    } catch (error) {
      console.error('Error starting checkout:', error);
      alert('Failed to start checkout. Please try again.');
    }
  }

  return (
    <div className="premium-card">
      <div className="premium-badge">⭐ Premium</div>

      <h3>Upgrade to Premium</h3>
      <p className="subtitle">Unlock all features...</p>

      <ul className="features-list">
        <li>✨ Unlimited AI generations</li>
        <li>🚀 Priority processing speed</li>
        <li>💎 Advanced customization options</li>
        <li>🎯 Priority customer support</li>
        <li>🔄 Cancel anytime</li>
      </ul>

      <div className="pricing">
        <span className="price">$9.99</span>
        <span className="period">/month</span>
      </div>

      <button
        className="upgrade-button"
        onClick={handleUpgradeClick}
      >
        Get Premium Now
      </button>
    </div>
  );
}

Part 4: (now the most scary part) Webhooks

Webhooks are important for keeping your database in sync with Stripe.

Setting Up for Local Development (see docs)

To test webhooks locally, you need the Stripe CLI:

Install Stripe CLI: Follow the installation guide
Login to Stripe CLI:
```
stripe login
```

Forward webhooks to your local server:

stripe listen --forward-to localhost:3000/api/webhook/stripe

Copy the webhook secret: The CLI will generate a webhook signing secret (starts with whsec_). Add this to your .env file, like this:
```
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx
```

Reference: Stripe Webhooks Documentation

Database Setup (Supabase)

First, create a table to store premium users. Run this SQL in your Supabase SQL editor:

CREATE TABLE PremiumUsers (
  user_email TEXT PRIMARY KEY,
  subscription_status TEXT NOT NULL,
  plan_type TEXT,
  credits_used INTEGER DEFAULT 0,
  subscribed_at TIMESTAMPTZ,
  expires_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  subscription_id TEXT,
  customer_id TEXT
);

it will look something like this:

Initialize Supabase Admin Client

Create a Supabase client with admin privileges, do not use this in your chrome extension, only put it in server side, for chrome extension create another supabase client with anon key or publishable key, this is the server-side:

// lib/supabase/supabaseAdmin.ts
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY!;

const supabaseAdmin = createClient(supabaseUrl, supabaseServiceKey, {
  auth: {
    autoRefreshToken: false,
    persistSession: false
  }
});

export default supabaseAdmin;

Function 2: Webhook Handler

This function processes all Stripe events and updates your database, it handles both one-time payment webhooks and subscription webhooks from stripe:

// app/api/webhook/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import supabaseAdmin from '@/lib/supabase/supabaseAdmin';
import stripe from '@/lib/stripe/stripeClient';

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

/**
 * Handles subscription creation and updates
 */
async function handleSubscriptionChange(subscription: Stripe.Subscription) {
  const customerId = subscription.customer as string;
  const customer = await stripe.customers.retrieve(customerId) as Stripe.Customer;

  if (!customer.email) {
    console.error('❌ Customer email is missing');
    throw new Error('Customer email is required');
  }

  // Convert Stripe timestamps (seconds) to ISO strings
  const subscribedAt = subscription.current_period_start
    ? new Date(subscription.current_period_start * 1000).toISOString()
    : new Date().toISOString();

  const expiresAt = subscription.current_period_end
    ? new Date(subscription.current_period_end * 1000).toISOString()
    : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();

  const dataToInsert = {
    user_email: customer.email,
    subscription_status: subscription.status,
    subscribed_at: subscribedAt,
    expires_at: expiresAt,
    subscription_id: subscription.id,
    customer_id: customerId,
    plan_type: subscription.items.data[0]?.price?.recurring?.interval || 'monthly',
  };

  // Upsert: insert new or update existing record
  const { data, error } = await supabaseAdmin
    .from('PremiumUsers')
    .upsert(dataToInsert, { onConflict: 'user_email' })
    .select();

  if (error) {
    console.error('❌ Database error:', error);
    throw error;
  }

  console.log('✅ Subscription updated:', data);
}

/**
 * Handles one-time payment completion
 */
async function handleOneTimePayment(session: Stripe.Checkout.Session) {
  const email = session.customer_email || session.customer_details?.email;

  if (!email) {
    console.error('❌ Customer email is missing from checkout session');
    throw new Error('Customer email is required');
  }

  // Set fixed duration for one-time payments (e.g., 30 days)
  const subscriptionDurationDays = 30;
  const subscribedAt = new Date(session.created * 1000);
  const expiresAt = new Date(subscribedAt);
  expiresAt.setDate(expiresAt.getDate() + subscriptionDurationDays);

  const dataToInsert = {
    user_email: email,
    subscription_status: 'active',
    subscribed_at: subscribedAt.toISOString(),
    expires_at: expiresAt.toISOString(),
    subscription_id: session.id,
    customer_id: session.customer as string,
    plan_type: 'one_time',
  };

  const { data, error } = await supabaseAdmin
    .from('PremiumUsers')
    .upsert(dataToInsert, { onConflict: 'user_email' })
    .select();

  if (error) {
    console.error('❌ Database error:', error);
    throw error;
  }

  console.log('✅ One-time payment recorded:', data);
}

/**
 * Main webhook handler
 */
export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get('stripe-signature');

  if (!signature) {
    return NextResponse.json(
      { error: 'No signature provided' },
      { status: 400 }
    );
  }

  let event: Stripe.Event;

  // Verify webhook signature
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err: any) {
    console.error('❌ Webhook signature verification failed:', err.message);
    return NextResponse.json(
      { error: `Webhook Error: ${err.message}` },
      { status: 400 }
    );
  }

  // Process the event
  try {
    switch (event.type) {
      // Subscription lifecycle events
      case 'customer.subscription.created':
      case 'customer.subscription.updated':
        await handleSubscriptionChange(event.data.object as Stripe.Subscription);
        break;

      case 'customer.subscription.deleted':
        const deletedSubscription = event.data.object as Stripe.Subscription;
        const deletedCustomer = await stripe.customers.retrieve(
          deletedSubscription.customer as string
        ) as Stripe.Customer;

        if (deletedCustomer.email) {
          await supabaseAdmin
            .from('PremiumUsers')
            .upsert(
              {
                user_email: deletedCustomer.email,
                subscription_status: 'canceled',
                subscription_id: deletedSubscription.id,
                customer_id: deletedSubscription.customer as string,
              },
              { onConflict: 'user_email' }
            );
          console.log('✅ Subscription canceled');
        }
        break;

      // Checkout completion
      case 'checkout.session.completed':
        const session = event.data.object as Stripe.Checkout.Session;

        if (session.mode === 'payment' && session.payment_status === 'paid') {
          // One-time payment
          await handleOneTimePayment(session);
        } else if (session.mode === 'subscription' && session.subscription) {
          // Subscription payment
          const subscription = await stripe.subscriptions.retrieve(
            session.subscription as string
          );
          await handleSubscriptionChange(subscription);
        }
        break;

      // Invoice events (for recurring subscriptions)
      case 'invoice.paid':
        const invoice = event.data.object as Stripe.Invoice;
        if (invoice.subscription) {
          const subscription = await stripe.subscriptions.retrieve(
            invoice.subscription as string
          );
          await handleSubscriptionChange(subscription);
        }
        break;

      case 'invoice.payment_failed':
        const failedInvoice = event.data.object as Stripe.Invoice;
        if (failedInvoice.subscription) {
          const subscription = await stripe.subscriptions.retrieve(
            failedInvoice.subscription as string
          );
          const customer = await stripe.customers.retrieve(
            subscription.customer as string
          ) as Stripe.Customer;

          if (customer.email) {
            await supabaseAdmin
              .from('PremiumUsers')
              .upsert(
                {
                  user_email: customer.email,
                  subscription_status: 'past_due',
                  subscription_id: subscription.id,
                  customer_id: subscription.customer as string,
                },
                { onConflict: 'user_email' }
              );
            console.log('✅ Subscription marked as past_due');
          }
        }
        break;

      default:
        console.log(`⚠️ Unhandled event type: ${event.type}`);
    }

    return NextResponse.json({ received: true }, { status: 200 });
  } catch (err: any) {
    console.error('❌ Error processing webhook:', err);
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    );
  }
}

run npm run dev command
then run the stripe CLI
generate a stripe checkout link,
open the link and
test a payment with dummy credit card 42424242...
see if you received the webhook events
finally:

Part 5: Deploying to Production (for free)

Deploy Your Serverless Functions

Deploy to Vercel (not sponsored btw):
```
vercel
vercel deploy --prod
```

Configure Production Webhooks

Go to your Stripe Dashboard → Workbench (bottom of screen) → Webhooks
Click Add Destination
Enter your endpoint: https://example.vercel.app/api/webhook/stripe
Select events to listen to:
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.paid
- invoice.payment_failed
Copy the Signing Secret and update your environment variable
deploy to vercel again with new webhook secret token

Part 6: Verifying Premium Status (demo)

When somebody use a premium feature in your extension, first verify that user’s subscription_status, like this, it’s server-side, not your extension-side:

// app/api/verify-premium/route.ts
import supabaseAdmin from '@/lib/supabase/supabaseAdmin';

/**
 * Checks if a user has an active premium subscription
 */
export async function isEligibleUser(userEmail: string): Promise<boolean> {
  try {
    const { data, error } = await supabaseAdmin
      .from('PremiumUsers')
      .select('*')
      .eq('user_email', userEmail)
      .single();

    if (error) {
      console.error('Database error:', error);
      return false;
    }

    if (!data) {
      return false;
    }

    const status = data.subscription_status.trim().toLowerCase();

    // Consider 'active' and 'trialing' as eligible
    // 'trialing' is for users in free trial period
    // paid is for one-time payment i guess
    return status === 'active' || status === 'trialing' || status === 'paid'
  } catch (error) {
    console.error('Error checking premium status:', error);
    return false;
  }
}

/**
 * API endpoint to verify premium status
 */
export async function POST(request: Request) {
  try {
    const { userEmail } = await request.json();

    if (!userEmail) {
      return new Response(
        JSON.stringify({ error: 'Email is required' }),
        { status: 400, headers: { 'Content-Type': 'application/json' } }
      );
    }

    const isPremium = await isEligibleUser(userEmail); 
    /// it will return false if the user is not in database or don't have any active subscription

    return new Response(
      JSON.stringify({ isPremium }),
      { status: 200, headers: { 'Content-Type': 'application/json' } }
    );
  } catch (error) {
    console.error('Verification error:', error);
    return new Response(
      JSON.stringify({ error: 'Internal server error' }),
      { status: 500, headers: { 'Content-Type': 'application/json' } }
    );
  }
}

Using Premium Verification in Your Extension

// utils/premiumCheck.ts

export async function checkPremiumStatus(userEmail: string): Promise<boolean> {
  try {
    const response = await fetch('https://your-app.vercel.app/api/verify-premium', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userEmail }),
    });

    if (!response.ok) {
      return false;
    }

    const { isPremium } = await response.json();
    return isPremium;
  } catch (error) {
    console.error('Error checking premium status:', error);
    return false;
  }
}

// Example usage in your extension
export async function usePremiumFeature(userEmail: string) {
  const isPremium = await checkPremiumStatus(userEmail);

  if (!isPremium) {
    console.log('this guy is not a premium guy');
    return;
  }

  // User is premium,
  console.log('✅ this guy is premium')
}

hey man!

congrats, you are pretty much done right now…

btw i assumed that you already implemented authentication (like Continue With Google) in your extension before adding stripe payments.

If you don’t know “how to add google auth” then checkout my boilerplate

thankyou so much for reading 💛
have a nice night...
bye bye :)

How to Implement Settings in Browser Extensions

Himanshu — Thu, 11 Dec 2025 11:52:50 +0000

here’s how i implement and manage settings in my chrome extension using local storage (e.g. isDark, userLanguage, etc…)

Why Proper Settings Management Matters

Maintainability: Good structure makes your code easier to update and debug
Performance: Efficient storage operations keep your extension fast
DRY: avoid repeating chrome.storage.sync everywhere

1. chrome.storage.sync vs chrome.storage.local

Browser extensions have access to two main storage APIs (avoid session storage, bcz you need to call this function to use it from content script:

// Source - https://stackoverflow.com/questions/74424746/not-able-to-access-storage-in-content-scripts-in-chrome-extension-manifest-v3

chrome.storage.session.setAccessLevel({ accessLevel: 'TRUSTED_AND_UNTRUSTED_CONTEXTS' });

so we only have two options, sync or local:

i like chrome.storage.sync because it Automatically syncs across all browsers where the user is logged in, (like their laptop, pc, etc), you don’t need to do anything, chrome will do it

Note: Throughout this blog, I use browser.storage instead of chrome.storage because i am using wxt framework to develop my extension , but you can easily replace browser with chrome keyword. Doesn't matter.

2. Designing Your Settings Structure

keep it flat. Avoid deep nesting because it makes updates/inserts/deletes harder.

❌ Bad Structure (Nested)

// Don't do this
{
  settings: {
    appearance: {
      theme: {
        mode: "dark",
        accentColor: "blue"
      }
    }
  }
}

To update mode, you'd need to:

Fetch the entire settings object
Navigate through nested properties
Update the value
Save everything back

✅ Good Structure (Flat)

// also keep settings and user info separate (if possible)

  userSettings: {
    isDark: true,
    isEnabled: true,
    userLang: "english",
    accentColor: "blue",
    fontSize: "medium"
  },


  userInfo: {
    userEmail: "example@gmail.com",
    isAuthenticated: true,
    creditsUsed: 54,
    favCategories: ['sci-fi', 'horror', 'thriller']
  }

3. Create default values

Always define default settings/values. These act as a fallback when settings don't exist yet (like on first install).

// utils/constants.js

export const DEFAULT_SETTINGS = {
  isDark: false,
  isEnabled: true,
  userLang: 'english',
  fontSize: 'medium',
  extensionActive: true,
  notificationsEnabled: true,
};

export const DEFAULT_USER_INFO = {
  userEmail: '',
  isAuthenticated: false,
  creditsUsed: 0,
  favCategories: [],
  userId: undefined,
  lastSync: undefined,
};

4. Creating Helper Functions

Never repeat chrome.storage.get() calls throughout your codebase. Instead, create reusable helper functions.

Reading from Storage

// utils/getStorage.js

import { DEFAULT_SETTINGS, DEFAULT_USER_INFO } from '@/utils/constants';

export async function getUserInfo() {
  const result = await browser.storage.sync.get(['userInfo']);

  if (result.userInfo) {
    return result.userInfo;
  }

  /// return default to avoid bugs
  return DEFAULT_USER_INFO;
}

export async function getUserSettings() {
  const result = await browser.storage.sync.get(['userSettings']);

  if (result.userSettings) {
    return result.userSettings;
  }

  return DEFAULT_SETTINGS;
}

Writing to Storage

// utils/updateStorage.js

/// updating userInfo
export async function updateUserInfo(key, value) {
  const result = await browser.storage.sync.get(['userInfo']);

  if (!result.userInfo) {
    console.log('❌ userInfo is empty');
    return;
  }

  const newUserInfo = { ...result.userInfo, [key]: value };

  await browser.storage.sync.set({
    userInfo: newUserInfo,
  });
}

/// updating settings
export async function updateUserSettings(key, value) {
  const result = await browser.storage.sync.get(['userSettings']);

  if (!result.userSettings) {
    console.log('❌ userSettings is empty');
    return;
  }

  const newUserSettings = { ...result.userSettings, [key]: value };

  await browser.storage.sync.set({
    userSettings: newUserSettings,
  });
}

How this works:

Fetch the current settings object
Create a new object with the updated value using spread operator
Save the new object back to storage

Initializing Storage on Install

Add this to your background script to set updefault values when users first install your extension:

// background.js or service-worker.js

  browser.runtime.onInstalled.addListener((object) => {
    if (object.reason === browser.runtime.OnInstalledReason.INSTALL) {
      setDefaultSettings().catch((e) => {
        console.log('failed to set default', e);
      });
      setDefaultUserInfo().catch((e) => {
        console.log('failed to set default', e);
      });
    }
  });

  /// OnInstalledReason.INSTALL make sure that this only run on install and not on updates

5. Settings Context (for Popup, Sidebar)

Now comes the powerful part: making settings available throughout your React popup without prop drilling.

Create a Custom Hook

// hooks/useStorageData.jsx

import { useState, useEffect } from 'react';
import { DEFAULT_SETTINGS, DEFAULT_USER_INFO } from '@/utils/constants';
import { getUserSettings, getUserInfo } from '@/utils/getStorage';
import { updateUserInfo, updateUserSettings } from '@/utils/updateStorage';

export function useStorageData() {
  const [settings, setSettings] = useState(DEFAULT_SETTINGS);
  const [userInfo, setUserInfo] = useState(DEFAULT_USER_INFO);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchUserData() {
      const userSettings = await getUserSettings();
      setSettings(userSettings);

      const userInfoStorage = await getUserInfo();
      setUserInfo(userInfoStorage);

      setLoading(false);
    }

    fetchUserData();
  }, []);

  function syncSettings(key, value) {
    const newSettings = { ...settings, [key]: value };
    updateUserSettings(key, value).then(() => setSettings(newSettings));
  }

  function syncUserInfo(key, value) {
    const newUserInfo = { ...userInfo, [key]: value };
    updateUserInfo(key, value).then(() => setUserInfo(newUserInfo));
  }

  return { settings, syncSettings, userInfo, syncUserInfo, loading };
}

Understanding the Code

1. Why initialize with default data?

const [settings, setSettings] = useState(DEFAULT_SETTINGS);

We use defaults as the initial state because:

Your app needs an immediate value (can't be undefined)
Prevents errors while data is loading from storage
Provides sensible fallbacks if storage is empty
The useEffect will replace these with real data once loaded

2. The useEffect Hook

useEffect(() => {
  async function fetchUserData() {
    const userSettings = await getUserSettings();
    setSettings(userSettings);
    // ... fetch userInfo ...
    setLoading(false);
  }
  fetchUserData();
}, []);

This runs once when the component mounts (empty dependency array []):

Fetches settings from storage
Updates React state with the real values
Sets loading to false once data is ready

3. The Magic of syncSettings

function syncSettings(key, value) {
  const newSettings = { ...settings, [key]: value };
  updateUserSettings(key, value).then(() => setSettings(newSettings));
}

This is incredibly useful because it:

Updates storage (persists the change)
Updates React state (triggers re-render)
Instantly reflects changes across all components using this hook
Provides optimistic updates (UI updates immediately, storage updates in background)

The same applies to syncUserInfo too.

6. Using Settings in Your Components

Now you can access settings from any component in your popup:

Example: Dark Mode Toggle

// pages/Settings.jsx

import { useStorageData } from '@/context/UserStorageData';

export default function Settings() {
  const { settings, syncSettings, loading } = useStorageData();

  if (loading) {
    return <div>Loading settings...</div>;
  }

  return (
    <div>
      <h2>Settings</h2>

      {/* Dark Mode Switch */}
      <div className="setting-item">
        <label htmlFor="dark-mode">Dark Mode</label>
        <input
          id="dark-mode"
          type="checkbox"
          checked={settings.isDark}
          onChange={(e) => syncSettings('isDark', e.target.checked)}
        />
      </div>

      {/* Language Selector */}
      <div className="setting-item">
        <label htmlFor="language">Language</label>
        <select
          id="language"
          value={settings.userLang}
          onChange={(e) => syncSettings('userLang', e.target.value)}
        >
          <option value="english">English</option>
          <option value="spanish">Spanish</option>
          <option value="french">French</option>
        </select>
      </div>
    </div>
  );
}

Using Settings in Other Components

// pages/Home.jsx

import { useStorageData } from '@/context/UserStorageData';

export default function Home() {
  const { settings, userInfo } = useStorageData();

  return (
    <div className={settings.isDark ? 'dark-theme' : 'light-theme'}>
      <h1 style={{ fontSize: settings.fontSize }}>
        Welcome back, {userInfo.userEmail || 'Guest'}!
      </h1>

      <p>Credits remaining: {userInfo.creditsUsed}/100</p>

      {settings.notificationsEnabled && (
        <div className="notification">
          You have new updates!
        </div>
      )}
    </div>
  );
}

Notice how:

✅ No prop drilling needed
✅ Settings are automatically synchronized
✅ Changes in Settings page instantly reflect in Home page

hope you enjoyed it 💛

btw i created a complete boilerplate for extensions that contains auth, subscription and more... so you can launch your extension in days not weeks, it's called extFast

thankyou and

bye bye :)

How to Implement Monthly Subscriptions in Browser Extensions

Himanshu — Tue, 09 Dec 2025 15:24:19 +0000

Here’s how i implemented monthly subscription inside my chrome extension without a website, just purely inside chrome extension and serverless function (at no cost).

Quick note: All the code in this tutorial comes from my boilerplate. If you'd rather skip implementing subscriptions, authentication, contact form, UI, landing page and other 1 billion boring stuff, check it out at extFast

Otherwise, let's code it

Overview of the Architecture

Before we dive in, let's understand what we're building:

The Payment Flow:

User clicks "Get Premium" button in your extension popup
Extension calls your serverless function to generate a checkout link
User gets redirected to Polar.sh checkout page
User completes payment
Polar.sh sends webhook to your serverless function
Serverless function stores user data in Supabase
Future premium feature requests verify subscription status

What You'll Need:

Serverless functions (deployed on Vercel at no cost)
- Function 1: Creates checkout links
- Function 2: Handles Polar webhooks
- Function 3 (optional): Serves premium features with verification
A Polar.sh account with a product (monthly, yearly, or one-time payment)
A popup page in your extension with an upgrade button
A database (we'll use Supabase) to store premium user data

The best part? Everything runs serverlessly, so you're not maintaining any backend infrastructure!

Tech Stack:

Payment Provider: Polar.sh (though you can use Stripe, Lemon Squeezy or any other provider)
Serverless Hosting: Vercel (again you can use whatever you want)
Database: Supabase (use whatever you want)
Extension Framework: i am using wxt but it works with any (vanilla JS, React, Vue, etc.)

(i’ll soon write a blog on Stripe too bcz i implemented it inside my extension without any problem, but for now let's start with polar)

Setting Up Polar.sh

Step 1: Create Your Polar Account

Go to https://sandbox.polar.sh/ for testing (use https://polar.sh for production)
Sign up for a free account

Step 2: Create an Organization

After logging in, create a new organization
Fill in your organization details (name, description, etc.)
This organization will be associated with your products

Step 3: Create Your Product

Navigate to the "Products" section in your Polar dashboard
Click "+ New Product"
Choose your product type:
- Recurring subscription (monthly/yearly)
- One-time payment (lifetime access)
Set your pricing (you can start with $5-10/month for testing)
Add a description
Save your Product ID, you'll need this later!

Step 4: Get Your API Keys

Go to Settings → General
Scroll down to the bottom and Copy your Access Token

Store these securely, we'll add them in .env file shortly.

Creating Your Serverless Functions

Now let's build the backend that powers your subscription system. We'll create serverless functions that handle checkout link generation and webhook processing.

Setting Up Your Project Structure

First, install the necessary dependencies:

npm install @polar-sh/sdk @polar-sh/nextjs

/// see docs: https://polar.sh/docs/guides/nextjs

If you're using Next.js (to create your serverless function [basically backend, not website]), your project structure should look like this:

your-project/
├── app/
│   └── api/
│       ├── checkout/
│       │   └── route.ts
│       └── webhook/
│           └── polar/
│               └── route.ts
├── lib/
│   ├── polarClient.ts
│   └── supabaseClient.ts
└── .env.local

Configure Environment Variables (server side, not extension)

Create a .env.local file in your project root:

POLAR_ACCESS_TOKEN=your_polar_access_token_here
POLAR_MONTHLY_PRODUCT_ID=your_product_id_here
POLAR_WEBHOOK_SECRET=your_webhook_secret_here
SUPABASE_URL=your_supabase_url_here
SUPABASE_ANON_KEY=your_supabase_anon_key_here

Create the Polar Client

Create lib/polarClient.ts:

import { Polar } from '@polar-sh/sdk';

export const polar = new Polar({
    server: 'sandbox', // remove this in production
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
});

Function 1: Checkout Link Generator

Create app/api/checkout/route.ts:

import { polar } from '@/lib/polarClient';

async function createCheckoutPolar(userEmail: string | null = null) {
  const results = await polar.checkouts.create({
    products: [process.env.POLAR_MONTHLY_PRODUCT_ID!],
    customerEmail: userEmail,
    successUrl: 'https://yourwebsite.com/checkout-success?checkout_id={CHECKOUT_ID}',
    allowDiscountCodes: true,
  });

  console.log('Polar checkout created:', results);
  return results;
}

export async function POST(request: Request) {
  try {
    const { userEmail } = await request.json();

    const session = await createCheckoutPolar(userEmail);

    return new Response(JSON.stringify({ checkout_url: session.url }), {
      status: 201,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    console.error('Error creating checkout URL:', error);

    return new Response(JSON.stringify({ status: 'error' }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}

What This Does:

Accepts a POST request with optional user email
Creates a checkout session via Polar.sh API
Pre-fills the user's email on the checkout page (great UX!)
Set a redirect url, when user made a successful payment it will redirect to your website (optional)

Pro Tip: You can skip this function entirely and hardcode a checkout link from Polar's dashboard if you don't need email pre-filling. Just go to Products → Checkout Links in Polar and grab the URL.

Deploy to Vercel

Push your code to GitHub
Connect your repository to Vercel
Add all your environment variables in Vercel's dashboard
Deploy!

Vercel will give you an API endpoint like: https://your-project.vercel.app/api/checkout

Save this URL – we'll use it in the extension.

Integrating with Your Extension

Now let's connect your extension to the serverless functions we just created.

Step 1: Create the Checkout Handler

Create a file handleCheckout.ts in your extension:

/// handleCheckout.ts

/// we will call this below function from our background script
/// it will call our vercel serverless function to generate a polar.sh checkout url
/// you can skip it and directly hard-code a checkout url, 
/// you can generate a checkout url by going into products/checkout links inside your polar dashboar
/// and put that url inside you background script and delete this function
/// we are generating checkout url only to pre-fill the user's email on the checkout page
export async function createCheckoutURL(email: string | null): Promise<string | null> {
  const CHECKOUT_ENDPOINT = 'https://your-project.vercel.app/api/checkout';

  try {
    const response = await fetch(CHECKOUT_ENDPOINT, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userEmail: email || null,
      }),
    });

    if (!response.ok) {
      console.error('Failed to create checkout URL');
      return null;
    }

    const results = await response.json();
    return results.checkout_url;
  } catch (error) {
    console.error('Error fetching checkout URL:', error);
    return null;
  }
}

// call this function from popup (or you can call it from content script too), 
// then it will send a message inside the background script to start the checkout flow
// then background script will call this above "createCheckoutURL" function to generate URL
// once the checkout url is generated, background script will redirect user to the checkout url
export async function invokeCheckout(email?: string) {
  await chrome.runtime.sendMessage({
    type: 'checkout',
    userEmail: email,
  });
}

Step 2: Your Background Script

Create or update background.ts:

import { createCheckoutURL } from './handleCheckout';

async function handleMessages(message: TMessage, sender: any, sendResponse: any) {
  if (message.type === 'checkout') {
    // Generate the checkout link
    const checkoutLink = await createCheckoutURL(message.userEmail);

    if (!checkoutLink) {
      console.error('❌ Failed to create checkout link');
      return;
    }

    // Redirect user to checkout page (no special manifest permission needed)
    chrome.tabs.create({ url: checkoutLink }, function (tab) {
      console.log('✅ Redirecting to checkout:', checkoutLink);
    });
  }
}

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  handleMessages(request, sender, sendResponse);
  return true; // Required for async responses
});

/// some typescript stuff, ignore it
type TMessage = {
  type: 'checkout';
  userEmail?: string;
};

How This Works:

Extension popup sends a message to background script
Background script calls your Vercel function
Vercel function generates a Polar checkout URL
Background script opens a new tab with the checkout URL
User completes payment on Polar's checkout page

Step 3: Create the Premium Upgrade Card (UI)

In your popup or content script, create a premium upgrade component:

// components/PremiumCardWidget.tsx

import { invokeCheckout } from './handleCheckout';

export default function UpgradeCard() {
  // Get user's email from your auth system or extension storage
  const userEmail = 'user@example.com'; // Replace with actual email

  async function handleUpgradeClick() {
    await invokeCheckout(userEmail);
  }

  return (
    <div className="premium-card">
      <h3>Upgrade to Premium</h3>
      <p>Unlock all features with Premium</p>
      <ul>
        <li>✨ Feature 1</li>
        <li>🚀 Feature 2</li>
        <li>💎 Feature 3</li>
      </ul>
      <button onClick={handleUpgradeClick}>
        Get Premium - $9.99/month
      </button>
    </div>
  );
}

User Experience Flow:

User clicks "Get Premium" button
Extension sends message to background script
New tab opens with pre-filled checkout form
User enters payment details on Polar.sh
After payment, user is redirected to your success page
Webhook triggers (we'll handle this next)

Now the most scariest part: Webhooks

Webhooks are how Polar.sh notifies your backend when important events happen (like successful payments or cancellations). This is the crucial piece that keeps your database synchronized with payment status.

Setting Up the Database

First, let's create a Supabase table to store premium users.

SQL Schema for Supabase:

CREATE TABLE PremiumUsers (
  user_email TEXT PRIMARY KEY,
  subscription_status TEXT NOT NULL,
  plan_type TEXT,
  credits_used INTEGER DEFAULT 0,
  subscribed_at TIMESTAMPTZ,
  expires_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  subscription_id TEXT,
  customer_id TEXT
);

Table Structure Explanation:

user_email: Primary key, ensures one subscription per email
subscription_status: 'active', 'cancelled', 'trialing', etc.
plan_type: 'monthly', 'yearly', 'lifetime'
credits_used: Track usage if you have consumption limits
subscribed_at: When subscription started
expires_at: When current period ends
subscription_id: Polar's subscription ID
customer_id: Polar's customer ID

Create Supabase Client (server, not extension)

Create lib/supabaseClient.ts:

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.SUPABASE_URL!;
const supabaseKey = process.env.SUPABASE_ANON_KEY!;  /// or Supabase Secret key if you have RLS policy enabled, anon key will not work i guess

export const supabase = createClient(supabaseUrl, supabaseKey);

Function 2: Webhook Handler

Create app/api/webhook/polar/route.ts:

import { Webhooks } from '@polar-sh/nextjs';
import { supabase } from '@/lib/supabaseClient';

// This function handles any subscription status change
async function handleSubscriptionChange(payload: any) {
  try {
    const { error } = await supabase
      .from('PremiumUsers')
      .upsert(
        {
          user_email: payload.data.customer.email,
          subscription_status: payload.data.status,
          subscribed_at: new Date(payload.data.currentPeriodStart).toISOString(),
          expires_at: new Date(payload.data.currentPeriodEnd).toISOString(),
          subscription_id: payload.data.id,
          customer_id: payload.data.customerId,
          plan_type: 'monthly',
        },
        { onConflict: 'user_email' }
      )
      .select();

    if (error) {
      console.error('❌ Supabase upsert failed:', error);
      throw error;
    }

    console.log('✅ Successfully updated subscription for:', payload.data.customer.email);
  } catch (error) {
    console.error('Error in handleSubscriptionChange:', error);
    throw error;
  }
}

// Export the webhook handler
export const POST = Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
  onSubscriptionActive: handleSubscriptionChange,
  onSubscriptionUpdated: handleSubscriptionChange,
  onSubscriptionRevoked: handleSubscriptionChange,
  onSubscriptionCanceled: handleSubscriptionChange, // avoid it bcz "onSubscriptionRevoked" will trigger on user's subscription end, which is better
});

What This Webhook Handles:

onSubscriptionActive: New subscription created
onSubscriptionUpdated: Subscription plan changed
onSubscriptionRevoked: Subscription cancelled/expired
onSubscriptionCanceled: User explicitly cancelled (but be a good person and let them use your service until their plan end after 30 days or something, don't instantly stop their access, avoid it)

The upsert operation is clever, it either inserts a new record or updates an existing one based on the email, so you never get duplicates.

Configure Webhook in Polar.sh

Deploy your webhook handler/function to Vercel
Copy your webhook endpoint: https://your-project.vercel.app/api/webhook/polar
Go to Polar dashboard → Settings → Webhooks
Click "Add Endpoint"
Paste your webhook URL
Select the events you want to receive (at minimum: subscription.active, subscription.updated, subscription.revoked)
Copy the webhook secret and paste it inside the .env.local file as POLAR_WEBHOOK_SECRET

Testing Your Webhook:

You can use ngrok to test your webhooks, see this doc

Handling Premium Users

Now that users can subscribe and your database stays updated, let's implement the verification logic for premium features.

Function 3: Premium Feature with Verification (demo)

Create app/api/generate-ai/route.ts (or any premium endpoint):

import { supabase } from '@/lib/supabaseClient';

async function isEligibleUser(userEmail: string): Promise<boolean> {
  try {
    const { data, error } = await supabase
      .from('PremiumUsers')
      .select()
      .eq('user_email', userEmail)
      .single();

    if (error) {
      console.error('Error fetching user:', error);
      return false;
    }

    if (!data) {
      return false;
    }

    const status = data.subscription_status.trim().toLowerCase();

    // Check if subscription is active or in trial period
    if (status === 'active' || status === 'trialing') {
      // Optional: Also verify expiration date
      const expiresAt = new Date(data.expires_at);
      const now = new Date();

      if (expiresAt > now) {
        return true;
      }
    }

    return false;
  } catch (error) {
    console.error('Exception in isEligibleUser:', error);
    return false;
  }
}

async function generateAIContent(userEmail: string, prompt: string) {
  const isEligible = await isEligibleUser(userEmail);

  if (!isEligible) {
    return {
      error: 'Premium subscription required',
      code: 'SUBSCRIPTION_REQUIRED',
    };
  }

  // User is verified premium, do your premium logic here
  // For example, call OpenAI API, generate content, etc.
  const aiResponse = await yourAIFunction(prompt);

  // Optional: Track usage
  await supabase
    .from('PremiumUsers')
    .update({ credits_used: data.credits_used + 1 })
    .eq('user_email', userEmail);

  return {
    success: true,
    content: aiResponse,
  };
}

export async function POST(request: Request) {
  try {
    const { userEmail, prompt } = await request.json();

    if (!userEmail) {
      return new Response(
        JSON.stringify({ error: 'User email required' }),
        { status: 400 }
      );
    }

    const result = await generateAIContent(userEmail, prompt);

    return new Response(JSON.stringify(result), {
      status: result.error ? 403 : 200,
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    console.error('Error in premium endpoint:', error);
    return new Response(
      JSON.stringify({ error: 'Internal server error' }),
      { status: 500 }
    );
  }
}

Call Premium Endpoint from Extension (demo)

In your extension, whenever you need to access premium features:

async function usePremiumFeature(userEmail: string, data: any) {
  const response = await fetch('https://your-project.vercel.app/api/generate-ai', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userEmail: userEmail,
      prompt: data.prompt,
    }),
  });

  const result = await response.json();

  if (result.error) {
    // Show upgrade prompt
    return null;
  }

  return result.content;
}

one last thing you need to do is set the CORS, in your vercel serverless:

configure next.config.js with allowed origins
read this doc for more info

Checklist

Let's make sure you've got everything set up correctly:

Polar.sh Setup

✅ Created sandbox/production account
✅ Created organization
✅ Created product with pricing
✅ Copied product ID
✅ Generated API access token
✅ Generated webhook secret (after adding you serverless function endpoint)

Serverless Functions (Vercel)

✅ Installed dependencies (@polar-sh/sdk, @polar-sh/nextjs)
✅ Created checkout endpoint (/api/checkout)
✅ Created webhook handler (/api/webhook/polar)
✅ Added all environment variables
✅ Deployed to Vercel

now you are pretty much done :)

Skip All This

implementing subscriptions is just the beginning. You still need authentication like signin with Google etc, a contact form, a privacy policy page, SEO, a landing page…. and the list goes on.

I packaged all this in extFast so you can skip the boring stuff and ship faster.

thankyou for reading,

bye bye :)

How to implement Google OAuth in browser extension without “Tabs” permission

Himanshu — Sun, 07 Dec 2025 12:15:17 +0000

Handling authentication, specifically Google OAuth is a nightmare inside extension. You have to deal with chrome.identity, redirect URIs, and complex manifest.json configurations.

But there’s a super simple way and nobody is talking about it…

Here’s how i implemented google OAuth and classic email and password signup inside my chrome extension without tabs permission, yupp you heard it right, it's possible with just ‘storage’ permission

The Architecture: How It Works

We aren't doing authentication inside the extension (bcz popup page can close in the middle of flow).
We are doing it on our website and passing the session token to the extension.

i used NextJS to create a web app but you can use react + vite too, and for auth i used supabase but you can use firebase or any other auth provider, make sure they give you user’s session tokens:

Here's the flow:

User installs the extension and is redirected to your web app's signup page
User authenticates using Google OAuth or email/password on the web app
After successful authentication, tokens are exposed in hidden DOM elements
A content script running on your web app extracts these tokens
Tokens are sent to the extension's background script
Background script creates a session and stores it locally
Now both your extension and web app are in sync

Setting up the Web App

First, we need an authentication context in our Next.js application to handle the user's state. We are using Supabase's onAuthStateChange listener to detect when a user logs in.

Step 1: The Auth Context

Create contexts/AuthContext.tsx. This provider manages the user session and makes it available throughout your app.

/// contexts/AuthContext.tsx

'use client';

import React, { createContext, useContext, useEffect, useState } from 'react';
import supabase from '@/lib/supabase/supabaseClient';

type AuthContextType = {
  user: SupabaseUser | undefined;
  session: SupabaseSession | undefined;
  loading: boolean;
  logout: () => Promise<{ error: Error | null }>;
};

type AuthProviderProp = {
  children: React.ReactNode;
};

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
}

export function AuthProvider({ children }: AuthProviderProp) {
  const [user, setUser] = useState<SupabaseUser | undefined>(undefined);
  const [session, setSession] = useState<SupabaseSession | undefined>(undefined);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    supabase.auth.onAuthStateChange((eventName, session) => {
      console.log('Auth state changed:', eventName, session);

      if (eventName === 'INITIAL_SESSION' && session?.user) {
        setUser(session.user);
        setSession(session);
      } else if (eventName === 'SIGNED_IN' && session?.user) {
        setUser(session.user);
        setSession(session);
      } else if (eventName === 'SIGNED_OUT') {
        setUser(undefined);
        setSession(undefined);
      }
    });
  }, []);

  const value = {
    user,
    session,
    loading,
    logout: () => supabase.auth.signOut(),
  };

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

The onAuthStateChange listener is crucial here. It fires whenever the authentication state changes, allowing us to update our UI and expose tokens when the user successfully logs in.

Step 2: Wrap Your app or main.tsx

Make sure to wrap your app app/layout.tsx with AuthProvider so the entire app has access to the user state. Like this:

/// app/layout.tsx
import { AuthProvider } from '@/context/AuthContext';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>
          {children}
         </AuthProvider>
      </body>
    </html>
  );
}

Step 3: Create the Authentication Page

Now let's build the actual authentication page where users will sign up or log in.

// app/auth/page.tsx
'use client';

import { useState } from 'react';
import supabase from '@/lib/supabase/supabaseClient';

export default function AuthPage() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(false);

  async function handleRegister() {
    setLoading(true);
    const { data, error } = await supabase.auth.signUp({
      email: email.trim(),
      password: password,
      ///optional
      options: {
        emailRedirectTo: process.env.NEXT_PUBLIC_AUTH_SUCCESS_URL, 
      },
    });

    setLoading(false);

    if (error) {
      console.error('Registration error:', error);
      // Handle error (show toast, etc.)
    }
  }

  async function handleGoogleLogin() {
    await supabase.auth.signInWithOAuth({
      provider: 'google',
      options: {
        redirectTo: process.env.NEXT_PUBLIC_AUTH_SUCCESS_URL,
        queryParams: {
          access_type: 'offline',
          prompt: 'consent',
        },
      },
    });
  }

  return (
    <div className="auth-container">
      <h1>Sign Up for Your Extension</h1>

      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />

      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />

      <button onClick={handleRegister} disabled={loading}>
        Sign Up with Email
      </button>

      <button onClick={handleGoogleLogin}>
        Continue with Google
      </button>
    </div>
  );
}

Step 4: Expose Tokens via Hidden DOM Elements

This is the bridge between your web app and extension. Add hidden elements to your footer (or any component) that will contain the authentication tokens.

// components/Footer.tsx
'use client';

import { useAuth } from '@/contexts/AuthContext';

const Footer = () => {
  const { session, user } = useAuth();

  return (
    <>
      {/* Hidden elements for extension's content script to read */}
      {session && (
        <div className="hidden">
          <div className="userEmailDiv">{user?.email}</div>
          <div className="accessTokenDiv">{session?.access_token}</div>
          <div className="refreshTokenDiv">{session?.refresh_token}</div>
        </div>
      )}

      {/* Rest of your footer content */}
      <footer>
        {/* Your footer content */}
      </footer>
    </>
  );
};

export default Footer;

The hidden class ensures these elements are hidden visually but remain in the DOM for the extension to access.

Building the Chrome Extension

Step 5: Create a Content Script to Extract Tokens

The content script runs on your web app's domain and watches for the authentication tokens to appear,
I'm using the WXT framework, but you can do the same with a plain content script too. Just make sure this script runs on your web app, bcz it will extract the supabase tokens from the footer of your website:

// authContentScript.ts
export default defineContentScript({
  matches: ['https://your-web-app.com/*'], // Replace with your domain
  allFrames: true,
  runAt: 'document_idle',
  main() {
    console.log('Auth content script initialized');

    function observeAuthTokens() {
      const observer = new MutationObserver((mutationList, observer) => {
        const accessTokenDiv = document.querySelector('.accessTokenDiv');

        if (accessTokenDiv) {
          const userEmailDiv = document.querySelector('.userEmailDiv');
          const refreshTokenDiv = document.querySelector('.refreshTokenDiv');

          if (accessTokenDiv.textContent?.trim() && refreshTokenDiv?.textContent?.trim()) {
            const accessToken = accessTokenDiv.textContent;
            const refreshToken = refreshTokenDiv.textContent;

            sendAuthTokens(accessToken, refreshToken);
            observer.disconnect();
          }
        }
      });

      observer.observe(document.body, {
        attributes: false,
        childList: true,
        subtree: true,
        characterData: true,
      });
    }

    observeAuthTokens();

    async function sendAuthTokens(access_token: string, refresh_token: string) {
      try {
        const response = await browser.runtime.sendMessage({
          type: 'signup',
          accessToken: access_token,
          refreshToken: refresh_token,
        });

        console.log('✅ Tokens sent to background script:', response);
      } catch (error) {
        console.error('Error sending tokens:', error);
      }
    }
  },
});

The MutationObserver watches for changes in the DOM. Once it detects the token elements are populated (in you web app’s footer or wherever you are exposing them), then it extracts them and sends them to the background script.

Step 6: Handle Authentication in Background Script

The background script receives the tokens and creates a Supabase session within the extension.

// backgroundScript.ts
import supabase from '@/lib/SupabaseClient';

type TMessage = {
  type: string;
  accessToken?: string;
  refreshToken?: string;
};

async function handleMessages(
  message: TMessage,
  sender: any,
  sendResponse: any
) {
  if (message.type === 'signup') {
    try {
      const { data, error } = await supabase.auth.setSession({
        access_token: message.accessToken!,
        refresh_token: message.refreshToken!,
      });

      if (error) {
        console.error('Session creation error:', error);
        sendResponse({ session: null, error: error.message });
        return;
      }

      // Store session in local storage
      await browser.storage.local.set({ session: data.session });

      sendResponse({ session: data.user });
    } catch (error) {
      console.error('Error in handleMessages:', error);
      sendResponse({ session: null, error: 'Unknown error' });
    }
  }
}

// Listen for messages from content scripts
browser.runtime.onMessage.addListener((request, sender, sendResponse) => {
  handleMessages(request, sender, sendResponse);
  return true; // Keep channel open for async response
});

Step 7: Create Extension Authentication Context

Finally, create an authentication context for your extension's popup and other components.

// contexts/AuthContext.tsx (Extension, not your web app)
import React, { createContext, useContext, useEffect, useState } from 'react';
import supabase from '../lib/SupabaseClient';

type AuthContextType = {
  user: SupabaseUser | undefined;
};

type AuthProviderProp = {
  children: React.ReactNode;
};

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
}

export const AuthProvider = ({ children }: AuthProviderProp) => {
  const [user, setUser] = useState<SupabaseUser | undefined>(undefined);

  useEffect(() => {
    async function initializeAuth() {
      // Check for stored session
      const { session } = await browser.storage.local.get('session');

      if (session && !user) {
        try {
          const { data, error } = await supabase.auth.setSession(session);

          if (data) {
            console.log('✅ Session restored:', data);
            await browser.storage.local.remove('session');
            setUser(data.user);
          }

          if (error) {
            console.error('Session restoration error:', error);
          }
        } catch (error) {
          console.error('Error initializing auth:', error);
        }
      }
    }

    initializeAuth();

    // Listen for auth state changes
    supabase.auth.onAuthStateChange((event, session) => {
      console.log('Extension auth state:', event, session);

      if (event === 'INITIAL_SESSION' && session?.user) {
        setUser(session.user);
      } else if (event === 'SIGNED_IN' && session?.user) {
        setUser(session.user);
      } else if (event === 'SIGNED_OUT') {
        setUser(undefined);
      }
    });
  }, []);

  const value = {
    user,
  };

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
};

Make sure to wrap your entire extension popup or app page app.tsx with AuthProvider so the entire popup has access to the user state. Like this:

/// App.tsx (extension, not web app)

import { AuthProvider } from '@/context/AuthContext';

export function App({ children }: AppProvidersProp) {
  return (
     <AuthProvider>
        {children}
     </AuthProvider>
  );
}

now whenever user open your extension's popup after signing up on your web app, this above AuthProvidor/useEffect/initializeAuth() will run and user automatically logged in in your extension.

phew

that's a lot of code, i know.

well if you don't want to build all this yourself, i actually created a Production-Ready extension boilerplate that contains auth, subscription, forget password, contact form and everything you need to ship and monetize extension fast, you can check it out here: extFast.web.app

thank you sooo much for reading, that's my first blog ❤️

have a nice day,

bye bye :)