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:

1. Settings (city, timezones) are personal to the device


2. The user might have different setups on different machines


3. 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);

Simple, reliable, works everywhere the extension runs.

Source code: github.com/oren-sys/weather-clock-dashboard