Manage Session State in Chrome Manifest V3: Service Workers

Are you experiencing mysterious bugs where your Chrome extension forgets user data or stops tracking events? If your extension worked fine in Manifest V2, you are likely suffering from service worker memory wipeouts.

In legacy Manifest V2, background pages ran continuously in the background. Developers could declare a global variable like `let currentUser = {}` and trust it would stay in memory all day.

Executive Summary

  • The Persistence Problem: Global variables in Manifest V3 are wiped when the background service worker shuts down after 30 seconds of inactivity.
  • Session Storage API: Chrome introduced chrome.storage.session as an in-memory, process-independent storage area that survives worker restarts.
  • Local vs Session Storage: Learn when to use session storage for temporary runtime cache versus chrome.storage.local for persistent user preferences.
  • Asynchronous Hydration: Best practices for hydrating state asynchronously inside event listeners before executing business logic.

Table of Contents

Chrome Extension Storage Options Compared

Storage AreaPersistence LifetimeCapacity LimitBest Use Case
chrome.storage.sessionCleared when browser closes10 MBTemporary runtime state, active tab IDs, auth tokens.
chrome.storage.localPersists across browser restarts10 MB (or unlimited with permission)User preferences, saved accounts, offline databases.
chrome.storage.syncSynced across user devices100 KB total (8 KB per item)Lightweight settings synced across work and home laptops.
Global JS VariablesCleared when worker shuts downRAM limited (volatile)Do not use for critical extension state in MV3.

Why Global Variables Fail in Manifest V3

Are you experiencing mysterious bugs where your Chrome extension forgets user data or stops tracking events? If your extension worked fine in Manifest V2, you are likely suffering from service worker memory wipeouts.

In legacy Manifest V2, background pages ran continuously in the background. Developers could declare a global variable like `let currentUser = {}` and trust it would stay in memory all day.

In Manifest V3, background pages no longer exist. They are replaced by ephemeral service workers that spin down after roughly 30 seconds of inactivity. When the worker shuts down, your JavaScript memory is cleared completely.

Using chrome.storage.session to Retain Runtime State

To solve this problem without writing data to the user’s hard drive, Chrome created the `chrome.storage.session` API. Session storage holds data in memory across service worker terminations, but automatically deletes it when the browser closes.

This makes session storage ideal for holding active tab queues, temporary API bearer tokens, and intermediate form progress. Because data is stored in memory outside the service worker process, it survives multiple restarts effortlessly.

To use session storage, declare the `’storage’` permission in your `manifest.json`. You can then call `chrome.storage.session.set()` and `chrome.storage.session.get()` exactly like local storage.

The Asynchronous Hydration Pattern

Because all Chrome storage APIs are asynchronous, you must adapt how your event listeners process incoming data. Never assume state is already available in memory when an alarm or message arrives.

Instead, implement the asynchronous hydration pattern. At the start of your event listener, fetch your required state from storage before executing application logic.

Once you update a value, write it back to storage immediately using `await chrome.storage.session.set({ [key]: value })`. This guarantees that subsequent wake-up calls always resume from verified data.

Sharing Session Storage with Content Scripts

By default, `chrome.storage.session` is restricted to trusted extension contexts like service workers and popups. Content scripts running on external web pages cannot access it.

If your architecture requires sharing session data with content scripts, you can configure access permissions programmatically. Call `chrome.storage.session.setAccessLevel({ accessLevel: ‘TRUSTED_AND_UNTRUSTED_CONTEXTS’ })` during extension startup.

This capability enables direct communication between web pages and your extension UI without setting up complicated message-passing channels.

Frequently Asked Questions

Does chrome.storage.session write data to the user’s hard drive?

No. Session storage is kept entirely in RAM and is never written to disk. All data is wiped automatically when the user closes their browser.

What is the storage quota for chrome.storage.session?

The default quota for session storage is 10 megabytes, which is more than enough for thousands of tokens, configurations, and cache objects.

Can I use IndexedDB inside a Manifest V3 service worker?

Yes. Modern Chromium service workers support IndexedDB for structured querying. However, for key-value state, chrome.storage.session is faster and simpler.

We hope this tutorial helped you level up your browser engineering. Explore related guides from our topic cluster:

Primary Sources & References

Written by the TeckScaler Editorial Engineering Team. We provide practical, beginner-friendly tutorials, architectural blueprints, and modern browser customization guides.