Introduction

Start building with the TurboStarter browser extension kit. WXT, Vite, auth, and shared backend patterns for Chrome, Firefox, and Edge.

Welcome to the TurboStarter browser extension documentation. This guide covers the WXT + Vite extension - popup, side panel, content scripts, background worker, shared web sessions, and multi-store publishing.

The extension is intentionally thin. Auth and checkout live on web; the extension inherits the session and calls the same API. Mobile shares that backend too - use those docs when you need native-only topics (push, IAP). Here we focus on what is unique to the extension runtime.

Looking to bootstrap quickly? Check out the TurboStarter CLI guide.

Demo apps

Try the live Chrome, Firefox, and Edge extensions (web and mobile demos are available too):

VisitWebsite

Philosophy

As simple as possible - easy to understand, easy to use, no overengineering.
As few dependencies as possible - stay in control of every part of the project.
As performant as possible - fast and light without unnecessary overhead.

Features

Extension-first capabilities below. For AI surfaces that open from the browser, see TurboStarter AI and the extension AI guide.

Extension structure

Every entrypoint lives under apps/extension/src/app - file-based routing for WXT.

Structure overview

Popup, options, side panel, new tab, content scripts, background, and more.

Pages & UI surfaces

Popup, options, side panel, new tab, and custom tab pages.

Content scripts & CSUI

Inject scripts and shadow-root React UI into web pages safely.

Background worker

Service worker for long-lived logic, alarms, and event listeners.

Message passing

Typed messaging between popup, content scripts, and background.

Extension storage

Persist local state with browser.storage for first-run flags and caches.

Shared session authentication

Users sign in once on the web app; the extension inherits that session - the same pattern as Notion and Google Workspace.

Auth overview

Why the extension shares Better Auth with the web app.

Session handling

Detect session state, open web login, and stay in sync on sign-out.

Trusted origins

Wire extension IDs and schemes so cookies and CSRF stay valid.

Web auth setup

Configure Better Auth on web first - required before extension auth works.

Billing & entitlements

Checkout stays on the web. The extension reads active plan and gates premium UI.

Extension billing

Plan badges, upgrade links, and how the extension consumes entitlements.

Feature-based access

Gate popup and side-panel features by plan - enforce on the API too.

Onboarding recipe

First-run welcome, web sign-in, and plan-gated empty states.

Web billing (source of truth)

Subscriptions, providers, and webhooks that power plan state.

Configuration & manifest

App configuration

WXT config, branding, and extension-wide settings.

Environment variables

API URLs and secrets for local, staging, and production builds.

Manifest

Permissions, entry points, and store-ready metadata via WXT.

Multiple environments

Dev, staging, and production builds for multi-browser targets.

Publishing to stores

Publishing checklist

Privacy, permissions, and listing requirements before you submit.

Chrome Web Store

Package, upload, and publish to the Chrome Web Store.

Firefox Add-ons

Submit to AMO with Firefox-specific packaging notes.

Edge Add-ons

Publish to the Microsoft Edge Add-ons store.

Updates

Ship new versions and update channels across browsers.

Marketing & store listing

Listing copy, screenshots, and go-to-market tips for extensions.

Organizations & API client

Same orgs and typed client as web - consumed from popup, options, and background.

Organizations

Active organization and membership in the extension UI.

API overview

How the extension talks to the shared serverless API.

Typesafe client

Fully typed client for queries and mutations from any entrypoint.

Database

Shared schema via the API - the extension never talks to the DB directly.

AI

Server-streamed AI

Same AI SDK chat patterns as web and mobile, inside the extension.

Chrome built-in AI

Experimental Gemini Nano path that runs locally in Chrome.

AI-assisted development

Rules and skills so AI editors follow WXT and monorepo conventions.

Security

Extension-specific attack surface: permissions, content scripts, and storage.

Security overview

Threat model for browser extensions in TurboStarter.

Permissions

Request the minimum host and API permissions you need.

Session security

Protect the shared web session inside the extension.

Content script safety

Isolate page context, avoid leaking privileged data to the DOM.

Storage security

What belongs in browser.storage vs the server.

Security checklist

Ship-ready checks before store submission.

Customization, analytics & monitoring

Styling & themes

Tailwind themes and dark mode across extension surfaces.

Components

Shared UI components for popup, options, and side panel.

Internationalization

Locales, language switching, and store `_locales` metadata.

Product analytics

Event tracking from popup, background, and content scripts.

Store listing analytics

Chrome / Firefox / Edge dashboard metrics vs in-extension tracking.

Monitoring

Error reporting across popup, background, and content scripts.

Feature flags

OpenFeature flags with in-memory, PostHog, or GrowthBook.

Tests & recipes

Unit tests

Fast unit tests for messaging helpers, hooks, and components.

E2E tests (Playwright)

Load the unpacked MV3 extension and cover popup, auth, and content scripts.

Build a feature

End-to-end pattern for shipping a new extension feature.

Use like LEGO blocks

Keep the entrypoints you need - popup and content scripts, or a full side panel - and remove the rest. Auth, billing, and orgs stay on the web API so the extension stays lean.

Scope of this documentation

Focus here is the WXT extension: structure, shared sessions, permissions, multi-store publishing, and extension UX. Shared backend topics (schema, payment providers, admin) are covered in the web docs. Native-only topics live in the mobile docs.

Enjoy!

Questions? Reach out at hello@turbostarter.dev.

Ship to the stores, keep the extension thin, and have fun! 🚀

Tech Stack

Explore the extension stack behind TurboStarter: WXT, Vite, React, shared auth, API client, and monorepo tooling.

CLI

Scaffold a new TurboStarter project from the CLI. Generate a configured monorepo with your chosen apps and packages in one command.

Extras

Bonus resources bundled with the extension kit: launch tips, community links, and shortcuts that speed up shipping your product.

FAQ

Answers to common TurboStarter extension questions about WXT setup, auth, store publishing, and project structure.