How to add payments to a CRXJS Vite extension

This guide adds payments to a Chrome extension built with Vite and CRXJS. At the end, the project carries Toolaby's client, its background starts Toolaby, and the paid action shows the paywall when it is refused. Buyers pay through Stripe Checkout, on your Stripe account. CRXJS reads its manifest from your code, so you add a few lines the command prints, once.

Before you begin

A tool registered in the dashboard, and its tool id: Tool id on the tool's page, or npx -y toolaby@latest tools. See the Quickstart.
Node.js 20 or later, for the command line.
A plan under the tool's Pricing, and Access set to Free uses or Nothing free, to see the paywall.
Nothing is needed from Stripe on Test: Toolaby makes a Stripe test account for your workspace.

A CRXJS project with manifest.json at its root is wired as a plain extension, with nothing to paste: see Add payments to a Chrome extension. The steps below are for a manifest in manifest.config.ts.

1. Wire the project

In the project's folder, run:

npx -y toolaby@latest wire <tool-id>

The first run shows a code to approve in your browser. On Test, the command writes the tk_test_… tool key. It writes toolaby.js (the client and the paywall, one ES module file), toolaby.config.js with the tool key, toolaby.d.ts, the Toolaby popup, and toolaby.manifest.js. Then it prints the lines below, with your own paths.

2. Add Toolaby to the manifest

Inside defineManifest({ … }):

manifest.config.ts

import { manifest as toolaby } from './toolaby.manifest.js';

...toolaby,
action: { default_popup: 'toolaby-popup.html' },

toolaby.manifest.js derives the extension's id, the storage permission and Toolaby's address from toolaby.config.js. The lines carry no values: swap in the Live key, and the manifest follows. wire remembers your popup as appPopup in toolaby.config.js, and the Toolaby popup opens it once the device may.

A content security policy of your own needs Toolaby's address. Wrap it as extension_pages: cspWithToolaby("…"), imported from toolaby.manifest.js.

CRXJS builds only the pages the manifest names. Keep your own popup built as a Vite input:

vite.config.ts

export default defineConfig({
  plugins: [crx({ manifest })],
  build: { rollupOptions: { input: { popup: 'src/popup/index.html' } } },
});

With a side panel, the command also prints side_panel: { default_path: 'toolaby-sidepanel.html' } for the manifest, and sidepanel: 'src/sidepanel/index.html' for the inputs.

4. Gate the paid action

For the background, the command prints two lines for the top of src/background.ts, or writes the file with them when there is none. To gate an action, pass your handlers to the same call:

src/background.ts

import { toolaby } from '../toolaby.js';

toolaby.startBackground({
  handlers: {
    async exportAll() {
      const permit = await toolaby.gate();
      if (!permit.allowed) return permit;
      return { allowed: true, file: await buildExport() };
    },
  },
});

gate() with no argument counts one free use. gate({ feature: 'export' }) asks whether the buyer's plan holds a feature. See Gate your extension.

5. Show the paywall

Your popup answers a refusal with the paywall:

src/popup/main.ts

import { toolaby } from '../../toolaby.js';

document.getElementById('export')!.addEventListener('click', async () => {
  const r = await chrome.runtime.sendMessage({ action: 'exportAll' });
  if (!r.allowed) return toolaby.showPaywall(r);
  save(r.file);
});

Add <toolaby-account></toolaby-account> at the foot of your popup by hand: the tag works on any page that loads toolaby.js, and shows the free uses left, the plan and Upgrade. Content scripts are bundled too, so one can import toolaby.js; its showPaywall() opens the checkout page in a new tab.

6. Build, check and pack

npm run build
npx -y toolaby@latest check --built dist

Load dist at chrome://extensions (Developer mode, then Load unpacked). For the Chrome Web Store, put the Live key in, build, and pack:

npx -y toolaby@latest wire <tool-id> --live --force
npm run build
npx -y toolaby@latest pack

The manifest takes the Live address from the key at build time. pack finds dist and writes <name>-<version>.zip, without the manifest's key, and refuses a build that carries a tk_test_ key. See Ship to the Chrome Web Store.

Add payments to a CRXJS extension

Before you begin

1. Wire the project

2. Add Toolaby to the manifest

4. Gate the paid action

5. Show the paywall

6. Build, check and pack

Next steps

Read next

WXT, Plasmo or CRXJS for a paid extension

Add payments to a WXT extension

Add payments to a Plasmo extension