Mastering Timed Tasks in Chrome Extensions: From Persistent Background to On‑Demand Execution

From Persistent Background to On‑Demand Wake‑Up

Early Chrome extensions allowed background scripts to stay resident, making setInterval‑based timers trivial. With Manifest V3 the background script became a Service Worker that is awakened only when needed and sleeps otherwise, so timers can miss their execution window if not handled correctly.

Implementation Options

Option 1: chrome.alarms API

The Chrome platform provides the chrome.alarms API for scheduling recurring tasks such as data sync or polling.

// Create an alarm named 'FunTesterAlarm' that fires every 15 minutes
chrome.alarms.create('FunTesterAlarm', { periodInMinutes: 15 });

// Listen for the alarm event
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'FunTesterAlarm') {
    console.log('FunTesterAlarm triggered');
    // Execute the scheduled work here
  }
});

Advantages: simple interface, officially supported.

Execution depends on Service Worker wake‑up; the browser may delay or skip the alarm.

Minimum interval is 1 minute, so sub‑second timing is impossible.

State is reset on each wake‑up; global variables cannot be relied upon.

Option 2: Content‑Script Based Timer

When a user visits a page, a content script can run a regular setInterval to perform checks or send heartbeats.

setInterval(() => {
  // Check DOM state or send a heartbeat request
}, 10000);

Limitations:

Cannot guarantee execution frequency; the timer stops when the page is closed.

Depends on user activity, so it cannot run as a true background task.

Option 3: Event‑Driven Simulated Timer

A more robust pattern records the last execution timestamp and decides whether to run the task when the extension starts or receives a message.

// Triggered when the extension starts (e.g., browser launch or reload)
chrome.runtime.onStartup.addListener(() => {
  checkAndRunTask();
});

function checkAndRunTask() {
  const now = Date.now();
  chrome.storage.local.get('lastRun', (res) => {
    const lastRun = res.lastRun || 0;
    // Run if more than 30 minutes have passed
    if (now - lastRun > 1000 * 60 * 30) {
      chrome.storage.local.set({ lastRun: now });
      // Execute the actual work here
    }
  });
}

This approach is less precise but offers better stability for low‑frequency, non‑critical background work.

Best Practices for Reliable Timers

Make tasks idempotent so that repeated execution does not produce duplicate data or side effects.

Log detailed execution information (start, end, errors) using console.log or a remote logging service to aid debugging.

Prevent duplicate runs by setting a lock or flag while a task is in progress.

Persist important state in chrome.storage (e.g., the last‑run timestamp) because Service Workers may be destroyed and lose in‑memory data.

Comprehensive Example

The following code demonstrates a complete, idempotent 30‑minute alarm with logging, state persistence, and error handling.

// Create a 30‑minute repeating alarm
chrome.alarms.create('FunTesterTask', { periodInMinutes: 30 });

chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'FunTesterTask') {
    console.log('FunTesterTask triggered at', new Date().toISOString());
    executeTask();
  }
});

function executeTask() {
  const now = Date.now();
  chrome.storage.local.get('lastRun', (res) => {
    const lastRun = res.lastRun || 0;
    if (now - lastRun > 1000 * 60 * 30) { // 30 minutes
      console.log('Executing FunTesterTask at', new Date().toISOString());
      performTask()
        .then(() => {
          console.log('FunTesterTask completed successfully');
          chrome.storage.local.set({ lastRun: now });
        })
        .catch((error) => {
          console.error('FunTesterTask failed:', error);
        });
    } else {
      console.log('FunTesterTask skipped, last run was too recent');
    }
  });
}

function performTask() {
  return new Promise((resolve) => {
    console.log('Performing FunTesterTask...');
    setTimeout(resolve, 2000); // Simulate async work
  });
}

Extended Ideas

In addition to chrome.alarms, timers can be driven by server push, WebSocket messages, or external scheduling services.

Server Push

Listen for push notifications (e.g., Firebase Cloud Messaging) and run tasks based on the payload.

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === 'SERVER_PUSH') {
    console.log('Received push message:', message.data);
    executeTask(message.data);
    sendResponse({ status: 'Task executed' });
  }
});

WebSocket Listener

Maintain a persistent WebSocket connection and trigger tasks when messages arrive.

const socket = new WebSocket('wss://example.com/socket');
socket.onopen = () => console.log('WebSocket connection established');
socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received WebSocket message:', data);
  executeTask(data);
};
socket.onerror = (error) => console.error('WebSocket error:', error);
socket.onclose = () => console.log('WebSocket connection closed');

External Scheduler

Handle HTTP messages from external services such as AWS Lambda or Google Cloud Functions via chrome.runtime.onMessageExternal.

chrome.runtime.onMessageExternal.addListener((message, sender, sendResponse) => {
  if (message.type === 'TRIGGER_TASK') {
    console.log('Received external trigger:', message.data);
    executeTask(message.data);
    sendResponse({ status: 'Task executed' });
  }
});

Conclusion

Implementing scheduled tasks in Chrome extensions requires understanding the Service Worker lifecycle, designing idempotent logic, persisting state, and thorough logging. While the built‑in chrome.alarms API satisfies most needs, combining it with push notifications, WebSocket listeners, or external schedulers can provide richer, real‑time capabilities.