An open-source browser extension starter for SaaS applications.
Website · Documentation · 中文教程 · Quick Start · Issues
MkExt is an open-source browser extension template for SaaS products that need a polished browser companion. Build on its ready-made Chrome and Firefox surfaces, replace the demonstrations with your workflow, and ship from one React codebase.
It brings together browser entrypoints, bearer-token authentication, shared state, localization, and cross-browser packaging. The included Domain Rating demos show two intentionally different page integrations: compact badges in Google Search results and a floating panel on ordinary webpages.
- Chrome and Firefox from one codebase — Chrome Manifest V3 and Firefox packages generated with WXT.
- Complete extension shell — popup, options, side panel, new tab, DevTools, background worker, and unlisted application pages.
- Extension-aware authentication — Better Auth email/password sessions, bearer-token storage, and optional Chrome Google Identity sign-in.
- Shared extension state — typed messaging, WXT storage, background request de-duplication, and short-lived Domain Rating caching.
- Product-ready UI — React 19, Tailwind CSS, Base UI, typed forms, light / dark / system themes, and English / Simplified Chinese support.
- Delivery workflow — Bun, Biome, unit tests, GitHub Actions, and separate Chrome and Firefox ZIP packages.
- WXT — Cross-browser extension framework and packaging.
- React and TypeScript — shared, typed UI across extension surfaces.
- Tailwind CSS and Base UI — Styling and accessible primitives.
- Better Auth — Bearer authentication and backend session integration.
- TanStack Query, React Hook Form, and Zod — server state, forms, and validation.
- Bun and Biome — Runtime, testing, formatting, and linting.
| Surface | Purpose | Source |
|---|---|---|
| Popup | Quick actions for the active tab and account | src/app/popup/ |
| Options / new tab / side panel | Full-page extension experiences | src/app/options/, newtab/, sidepanel/ |
| DevTools | Custom panel and Elements sidebar | src/app/devtools/, devtools-panel/ |
| Google Search | Inline DR badges beside search results | src/app/google-search.content.ts |
| Other webpages | Floating current-domain DR panel | src/app/domain-rating.content.ts |
| Background | Shared requests, cache, storage, and messages | src/app/background/ |
The two content scripts remain deliberately separate: Google Search uses result-level badges, while the floating panel excludes Google Search so the two presentation modes never overlap.
- Bun 1.3.14 or later
- Node.js 24 or later
- A Better Auth backend with bearer authentication enabled
git clone https://github.com/MkThingsHQ/mkext.git
cd mkext
bun install --frozen-lockfile
cp .env.example .env
bun run dev:chromeSet VITE_AUTH_URL in .env to your Better Auth backend. To work in Firefox,
run bun run dev:firefox instead. The Ahrefs key is bundled into the extension,
so use only a credential that is safe to expose and appropriately restricted.
| Command | Description |
|---|---|
bun run dev:chrome |
Start Chrome development mode |
bun run dev:firefox |
Start Firefox development mode |
bun run lint |
Run Biome checks |
bun run typecheck |
Type-check without emitting files |
bun test |
Run unit tests |
bun run build |
Create Chrome and Firefox ZIP packages |
bun run build:chrome |
Create only the Chrome package |
bun run build:firefox |
Create only the Firefox package |
src/
app/ WXT entrypoints, content scripts, and background worker
components/ Shared React feature and UI components
lib/ Auth, Domain Rating, i18n, messaging, storage, and utilities
locales/ English and Simplified Chinese source dictionaries
assets/ Global styles and extension icon source
types/ Shared TypeScript types and declarations
public/ Files copied unchanged into extension packages
Read the architecture guide for the current entrypoints, permission boundary, authentication flow, and release checks.
The Chinese tutorial series uses this repository as a working example rather than a generic API summary.
| Area | Guides |
|---|---|
| Start here | 教程总览, 浏览器扩展基础, 安装与第一次运行 |
| Build | 项目结构, 扩展入口, Content Script |
| Integrate | 权限与浏览器 API, 存储、消息与后台, Better Auth 认证 |
| Ship | UI、主题与国际化, 调试与测试, 构建、打包与发布 |
Contributions are welcome. Keep pull requests focused, include relevant tests and documentation with behavioral changes, and run the local gate before opening a pull request:
bun run lint
bun run typecheck
bun test
bun run build
git diff --checkRead CONTRIBUTING.md for extension permission, data handling, localization, and cross-browser review expectations.
- Website — Learn more about MkExt.
- Documentation — Explore the extension architecture and development tutorials.
- Contributing guide — Prepare a focused contribution.
- GitHub Issues — Report a bug or request a feature.
OpenFox is an independent developer building products and developer tools. His products include:
- MkAgent — A local-first, Pi-powered AI agent workspace for Desktop, WebUI, and CLI.
- TanStarter — Ship Faster with TanStack, Cost Less with Cloudflare.
- MkSaaS — Make Your AI SaaS Product in a Weekend.
- MkImage — Make Any Images Possible.
- Mkdirs — Launch AI-powered directory in 30 minutes.
- MkDollar — The all-in-one platform to help you make first dollar online.
Licensed under the Apache License 2.0. Preserve the third-party attribution in NOTICE when redistributing the project.