Versioning

A browser extension is a packaged artifact users install and keep until a new version passes the store and the browser updates them. You cannot silently overwrite what is already installed the way you redeploy a website. The version string in the manifest is the shared id between your zip, the store listing, and the browser.

That makes versioning less of a nice changelog habit and more of a release gate.

Why stores care so much?

• Uniqueness - Chrome, Edge, and Firefox reject an upload whose version was already used on that listing. There is no reuse, and you should not decrease.
• Review unit - each submission is a version. Notes, permission diffs, and reviewer questions all attach to it.
• Update delivery - users only move forward when a higher version is published and the browser fetches it.
• Support - "broken on 1.2.4, fine on 1.2.5" is how you bisect permission and host-access bugs.

Treat every upload as permanent history. Burned a version on a bad zip? Bump again. Do not try to resurrect the old number.

Version meaning

Semantic Versioning still works as a team language:

• Patch - fixes and polish that do not change the trust boundary
• Minor - new capabilities, especially optional permissions handled carefully
• Major - breaking UX or required new permissions that change what the extension can access

The number is not only for engineers. Store dashboards, rollout tools, and users who inspect chrome://extensions all see it. Prefer clean MAJOR.MINOR.PATCH on production uploads. Keep alpha/beta labels for internal builds if you need them.

Permissions considerations

Code size is not the only signal. Adding or widening host permissions / required permissions often means:

• another review pass
• a new consent prompt for existing users
• support questions that only make sense if you know which version introduced the change

When the trust boundary moves, bump at least minor and say so in the listing notes. A silent patch that suddenly asks for <all_urls> is how listings get delayed or users churn.

Release process

1. Decide what this release is (fix, feature, permission change).
2. Choose the next version accordingly.
3. Build one artifact from that version and upload that zip to every store you ship.
4. Write short release notes aimed at reviewers and users, not only at your changelog file.

Automate the upload if you want; do not automate away the version decision. The store will remember every number you burn.

In TurboStarter

The extension app version lives in apps/extension/package.json. WXT writes it into the generated manifest on build (including version_name when you use pre-release labels). The same value is available as appConfig.version in the UI.

Bump package.json, rebuild the zip, then follow Updates / the publishing checklist. You do not need a separate version field in wxt.config.ts for normal releases.

More on how WXT maps package version → manifest: WXT manifest config.