Browser Storage for Extension Developers: localStorage vs. browser.storage.local

When building a Firefox extension, you have two main options for client-side storage. Choosing wrong will either lock you out of sync features or break your extension on private browsing.

Here's the practical difference.

The Short Answer

Use browser.storage.local. Not localStorage. Not sessionStorage. Not indexedDB (unless you have very specific needs).

Here's why.

Why Not localStorage?

In a regular web page, localStorage is straightforward. But in an extension:

It doesn't work in background scripts.

// In a background script — THIS WILL FAIL
localStorage.setItem('key', 'value'); // ReferenceError: window is not defined

Background scripts don't have a window object. They run in a service worker context (MV3) or background page context (MV2), neither of which has localStorage.

It doesn't sync across devices.

Even if you use localStorage in a content script or popup, it's device-local only. browser.storage.sync can sync across Firefox installations.

Private browsing isolation.

In Firefox, extensions can be configured to run in private browsing. localStorage in private windows is isolated and cleared when the private window closes. browser.storage.local persists regardless.

browser.storage.local API

The API is promise-based and consistent across contexts:

// Save data
await browser.storage.local.set({
  theme: 'dark',
  city: 'San Francisco',
  clocks: [
    { zone: 'America/New_York', label: 'NYC' },
    { zone: 'Europe/London', label: 'London' }
  ]
});

// Read data
const prefs = await browser.storage.local.get(['theme', 'city', 'clocks']);
console.log(prefs.theme); // 'dark'

// Read all
const allPrefs = await browser.storage.local.get(null);

// Remove a key
await browser.storage.local.remove('city');

// Clear everything
await browser.storage.local.clear();

browser.storage.sync

For data you want to sync across the user's Firefox installations:

// Save to sync storage
await browser.storage.sync.set({ theme: 'dark' });

// Read from sync storage
const prefs = await browser.storage.sync.get('theme');

Limitations:

100KB maximum total data
8KB per key
512 items maximum
Firefox Sync must be enabled

For Weather & Clock Dashboard, I chose storage.local because:

Settings (city, timezones) are personal to the device
The user might have different setups on different machines
No Firefox Sync dependency

Listening for Changes

A useful pattern for reactive UIs:

browser.storage.onChanged.addListener((changes, areaName) => {
  if (areaName === 'local') {
    if (changes.theme) {
      applyTheme(changes.theme.newValue);
    }
    if (changes.city) {
      fetchWeather(changes.city.newValue);
    }
  }
});

This lets different parts of your extension react to storage changes without direct coupling.

Storage Size Limits

browser.storage.local has no limit by default, but requesting the unlimitedStorage permission removes any browser-imposed quota:

// manifest.json
"permissions": ["storage", "unlimitedStorage"]

For most extensions, the default is sufficient. Only needed for extensions storing large amounts of data.

Pattern: Settings with Defaults

const DEFAULTS = {
  theme: 'light',
  city: 'New York',
  clocks: [{ zone: 'America/New_York', label: 'Local' }]
};

async function getSettings() {
  const stored = await browser.storage.local.get(Object.keys(DEFAULTS));
  return { ...DEFAULTS, ...stored }; // stored values override defaults
}

This lets you add new settings with defaults without breaking existing users who don't have the new keys.

Practical Example

Weather & Clock Dashboard stores all user preferences this way:

// Load settings on new tab open
const settings = await browser.storage.local.get(null);
const city = settings.city || 'New York';
const clocks = settings.clocks || DEFAULT_CLOCKS;
const theme = settings.theme || 'light';

applyTheme(theme);
renderClocks(clocks);
fetchWeather(city);