How to Get Chrome Extension Updates to Users Faster

How Chrome extension updates actually work

Chrome checks for extension updates roughly every 5 hours. When it finds a new version in the Chrome Web Store, it downloads and installs it silently in the background. The user never sees a prompt — unless you changed permissions.

That "unless" is where most problems start. If your new version requests permissions or host access that the previous version did not have, Chrome will:

1. Disable the extension immediately
2. Show a badge on the puzzle icon in the toolbar
3. Wait for the user to manually click "Re-enable" and accept the new permissions

Until the user acts, they are stuck on the old version with the extension disabled. For a business-critical tool like an ads management extension, this is unacceptable.

1. Scope your host_permissions tightly

The host_permissions field in manifest.json is the number one cause of update friction. Every new origin you add triggers the re-consent flow.

"host_permissions": [
  "<all_urls>"
]

"host_permissions": [
  "https://ads.allegro.pl/*",
  "https://api.example.com/*"
]

"host_permissions": [
  "https://*.allegro.pl/*",
  "https://api.example.com/*"
]

2. Content scripts and match patterns

Content scripts have their own matches field that determines which pages they run on. Changing these patterns does not trigger a permission re-consent — but getting them wrong still delays your updates in other ways.

Match patterns that cause problems

"content_scripts": [{
  "matches": ["<all_urls>"],
  "js": ["content.js"]
}]

Match patterns done right

"content_scripts": [{
  "matches": [
    "https://ads.allegro.pl/*",
    "https://allegro.pl/ads/*"
  ],
  "js": ["content.js"],
  "run_at": "document_idle"
}]

Use run_at wisely

The run_at field does not affect update speed directly, but it matters for user experience after an update:

• document_idle (default) — safest, runs after the page is loaded
• document_end — runs after DOM is ready but before subresources
• document_start — runs before anything else, can slow down the page

Use document_idle unless you have a specific reason not to. Extensions that slow down page loads get lower ratings and more uninstalls.

3. The permissions field — plan your API surface upfront

The permissions array (separate from host_permissions) controls access to Chrome APIs like storage, tabs,alarms, and notifications. Adding a new permission here also triggers re-consent.

{
  "permissions": ["storage", "alarms"],
  "optional_permissions": ["notifications", "downloads"],
  "optional_host_permissions": ["https://analytics.example.com/*"]
}

4. Notify users in real time with version checking

Even if you do everything right with permissions and match patterns, Chrome's ~5-hour update cycle means users can be running stale code for hours. For critical bugfixes or features, that is too slow.

The solution: check the published version from inside your extension and prompt the user to update when a new version is available.

Why not a GitHub Action?

You might think CI/CD is the right place for version checking. We have a GitHub Action for permission escalation detection and it works great for catching problems before they ship. But for notifying end users about available updates, CI/CD does not help:

• A GitHub Action runs in your pipeline, not in the user's browser
• It burns CI minutes on every check
• It cannot tell the user "hey, click Update now"

What you need is a lightweight API that your extension can call at runtime to compare its own version against the version published in the Chrome Web Store.

Chrome Extension Version API

We built and open-sourced chrome-extension-version-api — a single-endpoint .NET service that queries the Chrome Web Store for the published version of any extension. It runs as a Docker container with built-in response caching.

GET /check-published-extension-version/{extensionId}

// Response (200 OK)
{
  "version": "1.23.4",
  "cached": false,
  "checkedAt": "2026-03-16T12:00:00Z"
}

docker run -p 8080:8080 ghcr.io/toumash/chrome-extension-version-api:latest

Extension-side implementation

In your content script — the code that runs on the page your users are already working on — check the published version and show an update notification directly in the UI:

// content.js — runs on the page the user is actively using
const EXTENSION_ID = chrome.runtime.id;
const VERSION_API = 'https://your-api.example.com';

async function checkForUpdate() {
  const localVersion = chrome.runtime.getManifest().version;
  const res = await fetch(
    `${VERSION_API}/check-published-extension-version/${EXTENSION_ID}`
  );
  const { version: storeVersion } = await res.json();

  if (storeVersion && storeVersion !== localVersion) {
    // Show an update banner on the page the user is working on
    const banner = document.createElement('div');
    banner.textContent = `Update available (v${storeVersion}). Please reload.`;
    banner.style.cssText =
      'position:fixed;bottom:16px;right:16px;padding:12px 20px;' +
      'background:#f97316;color:#fff;border-radius:8px;z-index:99999;' +
      'font-family:sans-serif;cursor:pointer;';
    banner.onclick = () => location.reload();
    document.body.appendChild(banner);
  }
}

// Check on page load
checkForUpdate();

FAQ

Related articles