Skip to main content
Extension.js does not replace or wrap browser storage APIs — it only compiles your code that calls them. The choice of storage area still matters. It shapes service-worker reliability, cross-browser consistency, and future data-structure changes.

​
Choose the right storage area

Storage areaUse whenNotes
storage.localdurable extension state on one devicebest default for most extension data
storage.syncsmall user preferences across signed-in browsersquota-sensitive and slower than local
storage.sessionshort-lived session stateuseful for ephemeral runtime coordination
storage.managedenterprise-managed policy valuesschema-driven, read-only to the extension
  • Use storage.local for feature state, caches, and durable settings.
  • Use storage.sync only for small, user-meaningful preferences.
  • Use storage.session for state that should not survive a full browser restart.
  • Treat storage.managed as a separate enterprise path, not your general settings mechanism.

​
Service-worker-friendly patterns

Manifest V3 (MV3) background service workers can stop and restart between events, so do not rely on in-memory state alone.
  • Restore critical state from storage on demand.
  • Cache in memory only as an optimization.
  • Keep startup work small so event handling stays responsive.
  • Persist versioned settings changes rather than assuming the background script stays running indefinitely.

​
Example settings module

const SETTINGS_KEY = 'settings'

export async function getSettings() {
  const result = await chrome.storage.local.get(SETTINGS_KEY)
  return result[SETTINGS_KEY] ?? {theme: 'system'}
}

export async function setSettings(nextSettings: {
  theme: 'system' | 'light' | 'dark'
}) {
  await chrome.storage.local.set({[SETTINGS_KEY]: nextSettings})
}

​
Storage design checklist

  1. Decide which values must survive browser restarts.
  2. Decide which values should sync across devices, if any.
  3. Version your stored data shape before the first release.
  4. Keep a migration path for renamed keys or changed structures.
  5. Avoid storing secrets in client-readable extension storage unless you fully accept that any extension code can read them.

​
Managed storage

If you use storage.managed, pair your runtime code with a valid storage.managed_schema file in manifest.json. Extension.js validates and emits that schema file to the output path. For the JSON resource details, see JSON.

​
Common mistakes

  • Using storage.sync for large data sets or caches.
  • Assuming background in-memory variables are durable in MV3.
  • Storing multiple disconnected keys without a versioning strategy.
  • Mixing enterprise-managed storage with user-editable settings without separating their access patterns.

​
Next steps

  • Declare schema-backed enterprise storage in manifest.json.
  • Review resource handling in JSON.
  • Move state between contexts with Messaging.