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

Enter fullscreen mode

Exit fullscreen mode

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.…