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
- Executive Summary
- Chrome Extension Storage Options Compared
- Why Global Variables Fail in Manifest V3
- Using chrome.storage.session to Retain Runtime State
- The Asynchronous Hydration Pattern
- Sharing Session Storage with Content Scripts
- Frequently Asked Questions
- Related Guides & Next Steps
- Primary Sources & References
Chrome Extension Storage Options Compared
| Storage Area | Persistence Lifetime | Capacity Limit | Best Use Case |
|---|---|---|---|
| chrome.storage.session | Cleared when browser closes | 10 MB | Temporary runtime state, active tab IDs, auth tokens. |
| chrome.storage.local | Persists across browser restarts | 10 MB (or unlimited with permission) | User preferences, saved accounts, offline databases. |
| chrome.storage.sync | Synced across user devices | 100 KB total (8 KB per item) | Lightweight settings synced across work and home laptops. |
| Global JS Variables | Cleared when worker shuts down | RAM 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.
Related Guides & Next Steps
We hope this tutorial helped you level up your browser engineering. Explore related guides from our topic cluster:
- The Ultimate Guide to Chrome Extension Development: Building for Manifest V3
- How to Fix Chrome Service Worker Inactivity Termination Bugs
- How to Build Your First Chrome Extension in 15 Minutes (Step by Step)
Primary Sources & References
Written by the TeckScaler Editorial Engineering Team. We provide practical, beginner-friendly tutorials, architectural blueprints, and modern browser customization guides.



