references/extensions/storage.md
GitHubChrome Storage API
Storage Areas
| Area | Persists | Syncs | Quota | Use For |
|---|---|---|---|---|
chrome.storage.local |
Yes | No | 10 MB | Most extension data |
chrome.storage.sync |
Yes | Yes (across devices) | 100 KB total, 8 KB/item | User preferences, small data |
chrome.storage.session |
Until browser close | No | 10 MB | Ephemeral state, survives SW restart |
Permission required: "storage"
Basic Operations
// Set
await chrome.storage.local.set({ key: 'value', count: 42, items: [1,2,3] });
// Get (with defaults)
const { key = 'default', count = 0 } = await chrome.storage.local.get(['key', 'count']);
// Get all
const allData = await chrome.storage.local.get(null);
// Remove
await chrome.storage.local.remove('key');
await chrome.storage.local.remove(['key1', 'key2']);
// Clear all
await chrome.storage.local.clear();
Change Listener (Works Across All Contexts)
chrome.storage.onChanged.addListener((changes, areaName) => {
for (const [key, { oldValue, newValue }] of Object.entries(changes)) {
console.log(`${areaName}.${key}: ${oldValue} → ${newValue}`);
}
});
storage.sync Quotas
Be aware of limits when using sync:
QUOTA_BYTES_PER_ITEM: 8,192 bytes per key-value pairMAX_ITEMS: 512 itemsQUOTA_BYTES: 102,400 bytes totalMAX_WRITE_OPERATIONS_PER_HOUR: 1,800MAX_WRITE_OPERATIONS_PER_MINUTE: 120
For large data, split across multiple keys or use chrome.storage.local.
storage.session Notes
- Only available in MV3
- Cleared when the browser closes (not just when SW terminates)
- Accessible from service worker, popup, side panel, etc.
- Good for: auth tokens, temporary caches, in-progress operations
Why Not localStorage?
localStorage works in popup and extension pages but NOT in service workers.
chrome.storage works everywhere and supports the cross-context change listener.
Always prefer chrome.storage.