
7 min read
From the studio
We build apps people actually keep.Tinkrd is a small indie studio making focused, high-quality apps for everyday life. See what we're working on.
View our appsIf you have tried scaffolding a Chrome extension from scratch recently, you know how fast the boilerplate gets out of hand. WXT is a framework that fixes most of that, and it is worth understanding before you commit to a build approach. Here is what it actually does and when it makes sense to reach for it.
What WXT Is and Why It Exists
WXT is an open-source framework specifically built for developing browser extensions, with first-class support for Chrome. It handles the build tooling, hot module replacement, manifest generation, and cross-browser compatibility so you can focus on writing the actual extension logic.
Before WXT, most teams either rolled their own Vite or Webpack config, or used a generic starter template that stopped being useful the moment requirements got specific. WXT is opinionated in the right places, meaning the folder structure and entry points follow a convention, but you can still drop in any frontend framework you want.
The project is maintained independently and has gained solid traction among indie developers. You can find the official documentation at wxt.dev.
How the WXT Project Structure Works
WXT uses a file-based routing convention similar to what Nuxt or Next.js do for web apps, applied to extension entry points instead of pages.
Key folders and what they do
- entrypoints/: Each file here becomes an extension entry point. A file named
popup.htmlbecomes the popup. A file namedbackground.tsbecomes the service worker. - public/: Static assets copied directly into the build output.
- wxt.config.ts: Top-level config for manifest details, browser targets, and Vite overrides.
A minimal config looks like this:
// wxt.config.ts
import { defineConfig } from 'wxt';
export default defineConfig({
manifest: {
name: 'My Extension',
description: 'Does something useful.',
permissions: ['storage', 'tabs'],
},
});
WXT reads that config and generates the manifest.json automatically during the build. You never hand-edit the manifest, which removes an entire category of mistakes.
Entrypoint example
// entrypoints/background.ts
export default defineBackground(() => {
browser.runtime.onInstalled.addListener(() => {
console.log('Extension installed');
});
});
The browser global WXT provides is polyfilled and works in Chrome, Firefox, and Safari without you importing anything extra.
WXT vs. Other Extension Tooling
Choosing between WXT and alternatives depends on your team size, browser targets, and how much configuration you want to own. Here is a direct comparison:
| Tool | Hot Reload | Manifest v3 Support | Cross-browser | Cost |
|---|---|---|---|---|
| WXT | Yes | Yes (default) | Chrome, Firefox, Safari, Edge | Free, open source |
| Plasmo | Yes | Yes | Chrome, Firefox | Free tier, paid cloud features |
| Custom Vite config | Partial | Manual setup | You handle it | Free, high maintenance |
| CRXJS | Yes | Yes | Chrome only | Free, less maintained |
WXT wins on cross-browser support and active maintenance. If you are only targeting Chrome and want maximum control, a custom Vite config is fine. If you want something that just works and keeps up with Manifest v3 changes, WXT is the practical choice right now.
Getting a WXT Extension Running in Minutes
Spinning up a WXT project takes about three commands and produces a working extension you can load immediately into Chrome.
npx wxt@latest init my-extension
cd my-extension
npm install
npm run dev
After running npm run dev, WXT builds the extension into a .output/chrome-mv3/ directory and watches for changes. To load it into Chrome, open chrome://extensions, enable Developer Mode, click Load Unpacked, and point it at that output folder. From that point, most changes reload automatically without you manually unpacking again.
This is the part that used to take an afternoon to set up manually. WXT handles all of it out of the box.
Where WXT Fits in a Real Extension Project
WXT is genuinely useful for indie developers and small teams building anything from a simple productivity tool to a more complex extension with a popup UI, content scripts, and background logic running together. The framework scales reasonably well from prototype to production.
At Tinkrd, we write about the tooling we actually evaluate for small, shipped products. For any new extension project that needs to run in more than one browser, WXT is the first thing we would reach for today, because the alternative is writing and maintaining build config that does not move the product forward.
If you want a broader view of what building an extension actually involves before committing to a framework, the Chrome extension development overview covers the full picture, from architecture decisions to publishing. And if you are still figuring out the basics of the publishing process, how to build and publish a Chrome extension walks through each step.
One honest caveat: WXT abstracts things, so when something breaks in an unusual way, you need to understand the underlying Chrome Extension APIs to debug it. The abstraction is thin enough that this is rarely a blocker, but it is worth knowing.
Building and Shipping a Production Extension with WXT
When you are ready to publish, WXT produces a zip file ready for the Chrome Web Store with one command.
npm run zip
That command runs the production build and packages the .output/chrome-mv3/ folder into a zip you upload directly to the Chrome Web Store Developer Dashboard. No manual zipping, no worrying about including hidden files or the wrong directories.
For Firefox, running npm run zip:firefox produces a separate zip targeting Manifest v2, since Firefox still requires it for most extensions. WXT manages the manifest differences between browser targets automatically based on which zip command you run.
The production build also handles things like stripping development console logs if you configure it to, and it tree-shakes unused code through Vite. The output is smaller and cleaner than most hand-rolled setups produce.
Frequently asked questions
Is WXT stable enough to use for a real extension I plan to ship?
Yes. WXT has been actively maintained and has a growing community of extensions built on it. It follows Manifest v3 requirements, which is the current Chrome standard. Like any open-source tool, you should pin your version and read the changelog before upgrading.
Can I use React or Vue inside a WXT project?
Yes. WXT is framework-agnostic. You can use React, Vue, Svelte, or plain TypeScript. The entrypoint convention works the same regardless of which UI framework you choose. Most developers add their framework of choice the same way they would in any Vite project.
Does WXT support Manifest v3?
WXT targets Manifest v3 by default for Chrome builds. This matters because Google has fully migrated the Chrome Web Store to Manifest v3. WXT handles the service worker setup, which is the biggest structural difference from Manifest v2 extensions.
How does WXT handle content scripts?
You define content scripts as files inside the entrypoints/ folder with a .content.ts suffix. WXT reads metadata from the file, such as the URL match pattern, and adds the content script configuration to the generated manifest automatically. You do not need to touch manifest.json by hand.
Can WXT build extensions for Firefox and Safari too?
Yes. WXT supports Chrome, Firefox, Safari, and Edge as build targets. You specify the target with the --browser flag or by running the browser-specific npm script. WXT adjusts the manifest format and polyfills appropriately for each target.
WXT removes a real category of friction from extension development without hiding how extensions actually work. For a small team that wants to ship something working rather than configure tooling indefinitely, it is one of the more honest productivity wins available right now.
We’re building in the open
Tinkrd is a small studio making thoughtful apps for families. Our first app is launching soon.