Using browser.storage.sync vs storage.local in Firefox Ex...

Using browser.storage.sync vs storage.local in Firefox Extensions: When to Use Each

Firefox extensions have two main storage options: browser.storage.sync and browser.storage.local. Picking the wrong one leads to frustrating UX. Here's how to think about it.

The Core Difference

	`storage.sync`	`storage.local`
Synced across devices	Yes (via Firefox Sync)	No
Quota	100KB (8KB per item)	10MB
Requires Firefox Sync	Yes, to actually sync	No
Falls back gracefully	Yes (local if not synced)	N/A

storage.sync: User Preferences

Use sync for anything that should feel the same across all the user's Firefox installations:

// Settings that should follow the user
await browser.storage.sync.set({
  temperatureUnit: 'celsius',   // °C or °F
  timeFormat: '24h',            // 12h or 24h
  theme: 'dark',                // dark or light
  defaultLocation: 'London',   // weather location
  worldClocks: [               // configured clocks
    { timezone: 'America/New_York', label: 'New York' },
    { timezone: 'Asia/Tokyo', label: 'Tokyo' },
  ]
});

If a user sets their preferred city on their laptop, it should appear on their desktop too.

storage.local: Cached Data

Use local for ephemeral data — API responses, cache, large blobs:

// Cache fetched weather data (don't sync — it's ephemeral)
await browser.storage.local.set({
  weatherCache: {
    London: {
      data: { temp: 15, description: 'Cloudy' },
      timestamp: Date.now()
    }
  }
});

Caching weather data in sync would hit quota limits fast and waste sync bandwidth on data that expires in 10 minutes.

Quota Handling

storage.sync has strict limits:

Total: ~100KB
Per item: 8KB
Number of items: 512

Always handle quota errors gracefully:

async function saveUserPreferences(prefs) {
  try {
    await browser.storage.sync.set(prefs);
  } catch (error) {
    if (error.message.includes('QUOTA_BYTES')) {
      console.warn('Sync storage quota exceeded, falling back to local');
      await browser.storage.local.set(prefs);
    } else {
      throw error;
    }
  }
}

Reading with Defaults

Always provide defaults when reading — the storage might be empty on first install:

const DEFAULTS = {
  temperatureUnit: 'celsius',
  timeFormat: '24h',
  theme: 'auto',
  defaultLocation: '',
  worldClocks: [],
};

async function loadPreferences() {
  const stored = await browser.storage.sync.get(DEFAULTS);
  // stored will contain stored values OR defaults for missing keys
  return stored;
}

Listening for Cross-Device Changes

When sync is active, settings can change from another device:

browser.storage.onChanged.addListener((changes, area) => {
  if (area !== 'sync') return;

  if (changes.theme) {
    applyTheme(changes.theme.newValue);
  }
  if (changes.temperatureUnit) {
    refreshWeatherDisplay();
  }
  if (changes.worldClocks) {
    rebuildClockList(changes.worldClocks.newValue);
  }
});

This is what makes sync powerful — changes propagate to all open tabs/windows automatically.

The Pattern I Use

In Weather & Clock Dashboard, the storage strategy is:

const SYNC_KEYS = ['theme', 'temperatureUnit', 'timeFormat', 'defaultLocation', 'worldClocks'];
const LOCAL_KEYS = ['weatherCache', 'lastUpdated'];

// On startup: load sync prefs, use local cache
async function init() {
  const prefs = await browser.storage.sync.get(DEFAULTS);
  applyPreferences(prefs);

  // Try to load cached weather first (instant)
  const { weatherCache } = await browser.storage.local.get('weatherCache');
  if (weatherCache && isFresh(weatherCache)) {
    displayWeather(weatherCache.data);
  }

  // Then refresh in background
  fetchAndCacheWeather(prefs.defaultLocation);
}

This gives instant load from cache, with the user's synced location preference, and fresh data arriving silently.

Common Mistakes

Caching API responses in storage.sync — Wastes quota and sync bandwidth
Not providing defaults — Silent failures on first install
Not listening for storage.onChanged — UI won't update when sync kicks in
Storing large blobs in sync — Base64 images, etc. will exceed the 8KB per-item limit

When Firefox Sync is Disabled

storage.sync falls back gracefully — it still works, just locally. You don't need to check whether Firefox Sync is enabled. The extension works the same on a single device; it just won't sync.

Weather & Clock Dashboard — free Firefox new tab extension with live weather, world clocks, search bar. No tracking, MIT licensed.

推荐订阅源

DEV Community