Chrome Extension Template: What to Use and How to Make It Work
Photo by https://kaboompics.com/ on Pexels

6 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 apps

Starting a Chrome extension from a blank folder is slower than it sounds. A good chrome extension template gives you the manifest, folder structure, and build config you need so you can skip the setup and write actual code. Here is what to look for, how to adapt one, and where the common traps are.

What a Chrome Extension Template Actually Gives You

A Chrome extension template is a starter project that includes the required files and wiring so you do not have to build them from scratch every time. At minimum, a useful template ships with a manifest.json set to Manifest V3, a basic popup, a background service worker, and a content script stub. The better ones add a build tool like Vite or webpack, TypeScript support, and a hot-reload dev workflow.

What a template does not give you is logic. The business logic, the UI, the permissions your extension actually needs, all of that is still on you. Think of a template as the scaffolding, not the building.

If you are newer to this space, it helps to understand what Chrome extension development actually takes before picking a template, because the template you need depends heavily on how complex your extension will be.

The Core Files Every Template Must Include

A complete chrome extension template needs a specific set of files to work in Chrome. Missing any one of them either breaks the extension or sends you back to documentation you did not plan to read.

manifest.json

The manifest is the single most important file. Chrome reads it first and uses it to understand what your extension is, what permissions it needs, and where your scripts live. As of now, all new extensions must use Manifest V3, which replaced V2. A minimal starting manifest looks like this:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "description": "Does one thing well.",
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "background": {
    "service_worker": "background.js"
  },
  "permissions": ["storage"]
}

The rest of the required structure

Beyond the manifest, a solid template includes at least these files:

Comparing the Most Common Template Options

Several good chrome extension templates exist, each with different trade-offs on stack and complexity. Here is a quick comparison of the options most indie developers actually use.

Template / Starter Stack Build Tool Cost Best for
chrome-extension-boilerplate-react React, TypeScript webpack Free React devs who want a full setup fast
crxjs/vite-plugin Any JS framework Vite Free Fast hot-reload, modern tooling
Plasmo Framework React, TypeScript Custom (Parcel-based) Free (paid tiers exist) Beginners who want the most hand-holding
Plain HTML starter (manual) Vanilla JS None Free Simple extensions with no build step

Our recommendation for most small projects: if you already know React, use the crxjs Vite plugin and add React yourself. It stays out of your way and the dev experience is noticeably faster than webpack setups.

How to Customize a Template Without Breaking It

Most developers break a template in the same two places: permissions and content security policy. Here is the safe order to follow when adapting any chrome extension template.

  1. Rename the extension in manifest.json first, name, version, description.
  2. Trim permissions to only what you need. Chrome will flag extensions that request too many permissions during review.
  3. Replace the popup UI without touching the background service worker until you understand what it does.
  4. Test in dev mode by loading the unpacked extension at chrome://extensions before touching anything else.
  5. Add your content scripts last, once the popup and background are confirmed working.

This matters more than it sounds. At Tinkrd, when we were exploring browser tooling for internal use, we found that developers most often break their extension by editing files they did not realize were connected. The manifest is the source of truth. When something stops working, check there first.

When to Build Your Own Template Instead

Building your own chrome extension template makes sense when you ship multiple extensions and find yourself re-adding the same patterns every time. If you are on your second or third extension, a custom internal template with your preferred linting rules, folder conventions, and a pre-wired messaging utility will save real time.

A minimal custom template takes about two hours to put together from a working extension. Fork your cleanest project, strip the business logic, add a README, and push it to a private repo. That is it.

For a broader look at the full development process, the guide on how to build and publish a Chrome extension walks through each stage from setup to the Chrome Web Store.

If you are still figuring out whether you have the technical baseline to start, this honest breakdown covers what skills you actually need.

Frequently asked questions

Is Manifest V3 required for new Chrome extensions?

Yes. Google requires Manifest V3 for all new extensions submitted to the Chrome Web Store, and existing V2 extensions have been migrated or disabled. Any chrome extension template you use today should already be on V3. If it is not, do not use it.

Can I use a React or Vue component in a Chrome extension?

Yes, you can use any JavaScript framework in a Chrome extension popup or options page. You just need a build step, typically Vite or webpack, to bundle your components into plain JS files that Chrome can load. Templates like crxjs handle this automatically.

How do I add hot reload to a Chrome extension during development?

The crxjs Vite plugin is the cleanest way to get hot module replacement working in a Chrome extension. After setting it up, changes to your popup or content scripts reflect almost immediately without manually reloading the extension. It is a genuine quality-of-life improvement over manually refreshing.

Do I need TypeScript in my chrome extension template?

No, TypeScript is optional, but it helps for anything beyond a simple extension. The Chrome extension API surface is large and TypeScript with the @types/chrome package gives you autocomplete and catches mistakes before runtime. For a one-file script, skip it. For anything with multiple message-passing components, add it early.

Can I publish an extension built from a public template to the Chrome Web Store?

Yes. Public templates are open source and designed to be used this way. Just make sure you have replaced all placeholder content, removed unused permissions, and that the extension does something genuinely useful. The Chrome Web Store review team will reject extensions that appear to be bare templates with no real function.

A good chrome extension template does not write your extension for you, but it removes the friction that stops many developers from starting at all. Pick one that matches your stack, keep the manifest clean, and build the one small thing you actually set out to build.

We’re building in the open

Tinkrd is a small studio making thoughtful apps for families. Our first app is launching soon.

See what we’re building

T
The Tinkrd Team

We are a small independent app studio in California. We write about what we are learning as we build and ship products, from first commit to first customer.