Chrome Extension Alarms & Scheduling — Developer Guide

5 min read

Background Scheduling with chrome.alarms

Introduction

chrome.alarms is THE way to schedule background tasks in MV3
Replaces setInterval/setTimeout which don’t survive service worker termination
Requires "alarms" permission
Cross-ref: docs/permissions/alarms.md

manifest.json

{
  "permissions": ["alarms"],
  "background": { "service_worker": "background.js" }
}

Creating Alarms

One-Time Alarm

chrome.alarms.create("checkUpdates", {
  delayInMinutes: 5  // Fire once, 5 minutes from now
});

Repeating Alarm

chrome.alarms.create("syncData", {
  delayInMinutes: 1,     // First fire after 1 minute
  periodInMinutes: 30    // Then every 30 minutes
});

Alarm at Specific Time

chrome.alarms.create("dailyReport", {
  when: new Date("2024-01-15T09:00:00").getTime()  // Unix timestamp
});

Handling Alarms

chrome.alarms.onAlarm.addListener((alarm) => {
  switch (alarm.name) {
    case "checkUpdates":
      checkForUpdates();
      break;
    case "syncData":
      syncDataToServer();
      break;
    case "dailyReport":
      generateReport();
      break;
  }
});

Register listener at TOP LEVEL of service worker (not inside async functions)
Handler wakes up the service worker if it was terminated

Managing Alarms

Get Alarm Info

chrome.alarms.get("syncData", (alarm) => {
  if (alarm) {
    console.log("Next fire:", new Date(alarm.scheduledTime));
    console.log("Period:", alarm.periodInMinutes, "minutes");
  }
});

List All Alarms

chrome.alarms.getAll((alarms) => {
  alarms.forEach(a => console.log(a.name, new Date(a.scheduledTime)));
});

Cancel Alarms

chrome.alarms.clear("syncData");    // Cancel specific alarm
chrome.alarms.clearAll();            // Cancel all alarms

MV3 Minimum Interval

Minimum period: 30 seconds in production (was 1 minute, reduced in Chrome 120+)
In development (unpacked): can be shorter
For sub-30-second tasks, use chrome.alarms as a wake-up and then use setTimeout within the handler

Common Patterns

Periodic Data Sync

// Setup on install
chrome.runtime.onInstalled.addListener(() => {
  chrome.alarms.create("sync", { periodInMinutes: 60 });
});

// Handle sync
chrome.alarms.onAlarm.addListener(async (alarm) => {
  if (alarm.name === "sync") {
    const data = await fetchFromServer();
    const storage = createStorage(defineSchema({ lastSync: 'number', data: 'string' }), 'local');
    await storage.setMany({ lastSync: Date.now(), data: JSON.stringify(data) });
  }
});

Badge Update (Unread Count)

chrome.alarms.create("updateBadge", { periodInMinutes: 5 });
chrome.alarms.onAlarm.addListener(async (alarm) => {
  if (alarm.name === "updateBadge") {
    const count = await getUnreadCount();
    chrome.action.setBadgeText({ text: count > 0 ? String(count) : "" });
  }
});

Reminder System

User sets reminders via popup
Store reminder times with @theluckystrike/webext-storage
Create alarm for each reminder
Show chrome.notifications when alarm fires

Session Cleanup

Periodic cleanup of stale data in storage
clearAll() on extension update, recreate needed alarms

Alarms + Storage Integration

import { createStorage, defineSchema } from '@theluckystrike/webext-storage';
const storage = createStorage(defineSchema({
  syncInterval: 'number',
  lastSync: 'number'
}), 'sync');

// User changes sync interval in options
async function updateSyncInterval(minutes) {
  await storage.set('syncInterval', minutes);
  await chrome.alarms.clear("sync");
  chrome.alarms.create("sync", { periodInMinutes: minutes });
}

Best Practices

Create alarms in chrome.runtime.onInstalled — they persist across restarts
Use descriptive alarm names — easier to debug
Always register onAlarm at top level of service worker
Don’t create duplicate alarms — check with get() first or just overwrite
Handle the case where alarm fires while offline (for network tasks)
Log alarm activity for debugging

Common Mistakes

Using setTimeout/setInterval — doesn’t survive SW termination
Registering onAlarm inside an async function — listener won’t catch events
Setting period less than 30 seconds — silently clamped to minimum
Not handling extension update — alarms persist but handlers may change
Creating alarm with same name overwrites previous — can be feature or bug

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

Turn Your Extension Into a Business

Ready to monetize? The Extension Monetization Playbook covers freemium models, Stripe integration, subscription architecture, and growth strategies for Chrome extension developers.

← Previous ai-llm-integration-extensions Next → architecture-patterns