Chrome Extension Versioning — Semantic Versioning and Auto-Update Strategy

5 min read

Chrome Extension Versioning — Semantic Versioning and Auto-Update Strategy

Effective version management is critical for maintaining Chrome extensions that serve thousands or millions of users. This guide covers the version format, semantic versioning principles tailored for extensions, the auto-update infrastructure, differential updates, staged rollouts, and maintaining a comprehensive version history.

Version Format in manifest.json

Chrome extensions use a specific version format defined in the manifest. The version field in manifest.json is mandatory and must follow a structured pattern:

{
  "manifest_version": 3,
  "version": "1.2.3",
  "version_name": "1.2.3 Stable"
}

The version string accepts 1 to 4 dot-separated integers, each ranging from 0 to 65535. For example, "1.0.0", "2.1.3.456", and "0.0.0.1" are all valid. The optional version_name field allows you to display a friendlier version string in the Chrome Web Store listing and the extension management page, such as "Beta 2.0" or "v1.2.3 RC".

Chrome requires that each uploaded version must have a higher version number than the previous one. You cannot reuse or decrease version numbers—this is enforced by the Chrome Web Store during submission.

Semantic Versioning for Extensions

Semantic versioning (SemVer) provides a systematic approach to communicating the nature of changes between releases. While Chrome extensions don’t strictly require SemVer, adopting it improves user understanding and developer coordination.

Major versions (X.0.0) indicate breaking changes: removing APIs, changing permission requirements, or overhauling the core architecture. These require users to reinstall or manually update, as automatic updates may not handle breaking changes gracefully.

Minor versions (0.X.0) introduce new features without breaking existing functionality. Adding new optional permissions, introducing new content scripts, or expanding the options page are all minor version increments.

Patch versions (0.0.X) cover bug fixes, performance optimizations, documentation updates, and minor UI adjustments that don’t alter functionality or add features.

For Chrome extensions, a fourth component is sometimes used: major.minor.patch.build. The build number can represent CI/CD pipeline build identifiers or timestamp-based versioning, though this is optional and primarily useful for internal tracking.

Understanding update_url and Auto-Update Infrastructure

Chrome’s auto-update system relies on the update_url field in the manifest, which points to an update manifest (XML) that tells the browser where to find newer versions. For extensions hosted on the Chrome Web Store, this URL is managed automatically:

{
  "update_url": "https://clients2.google.com/service/update2/crx"
}

For self-hosted extensions or enterprise distributions, you can host your own update manifest:

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0' appid='YOUR_EXTENSION_ID'>
  <updatecheck codebase='https://example.com/extension.crx' version='1.2.3' />
</gupdate>

The browser periodically checks this URL—typically every few hours—to determine if a newer version is available. When found, Chrome downloads and installs the update automatically in the background.

For extensions distributed through the Chrome Web Store, Google handles the update infrastructure entirely. The system automatically notifies users with the extension’s update mechanism, and you don’t need to manage update manifests manually.

Differential Updates

Chrome implements differential updates (also called delta updates) to minimize bandwidth usage and speed up the update process. Instead of downloading the entire extension package for each update, Chrome downloads only the binary differences between the old and new versions.

This is particularly valuable for large extensions with significant codebases. A 10MB extension might only require a 500KB differential update rather than a full 10MB download. Chrome handles this automatically—the developer doesn’t need to configure anything special.

The differential update system works by comparing the previous version’s CRX file with the new one. Chrome determines whether to apply a differential update based on the age of the user’s current version and the availability of delta files on the server.

For Chrome Web Store submissions, Google generates and serves differential updates automatically. If you’re self-hosting, you may need to use tools like crxmake or Google’s omaha server to generate delta updates.

Staged Rollouts for Risk Mitigation

Staged rollouts allow you to gradually release new versions to a subset of users, monitoring for issues before a full deployment. This is essential for catching bugs, crashes, or user complaints that might not appear in testing.

The Chrome Web Store supports percentage-based rollouts directly from the developer dashboard. You can start with 5% of users, then increase to 10%, 50%, and finally 100%. At each stage, monitor:

To use staged rollouts, upload your new version through the developer dashboard and select the desired percentage instead of immediately publishing to 100%. The rollout can be paused or increased at any time.

For extensions not on the Chrome Web Store, staged rollouts require custom infrastructure—hosting different versions at different URLs and directing user updates accordingly.

Maintaining Version History

A clear version history serves multiple purposes: it helps users understand what’s changed, assists your support team in diagnosing issues, and provides an audit trail for compliance.

Maintain your version history in multiple places:

  1. CHANGELOG.md: Keep a running changelog in your repository documenting all changes by version
  2. Git tags: Tag each release with version numbers (git tag -a v1.2.3 -m "Release 1.2.3")
  3. Chrome Web Store release notes: Write concise release notes for each upload
  4. GitHub releases: If your extension is open-source, use GitHub releases to document changes

A well-maintained version history entry might look like:

## Version 1.2.0 (2024-01-15)

### Added
- Dark mode support in options page
- New `storage.getBackgroundColor()` API method

### Fixed
- Fixed popup not closing on outside click (#123)
- Resolved memory leak in background worker

### Changed
- Updated minimum Chrome version to 120

Document not just what changed, but why—especially for breaking changes or permission additions. This helps users understand the impact of updating.

Best Practices Summary

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article
No next article