64

I'm developing a Chrome extension and I need to store some data and then get it in some point. I did investigation on available storages and came across to the following ones: window.localStorage and chrome.storage.local.

So my question is, which one is the right choice to use in Chrome extensions:
window.localStorage or chrome.storage.local?

P.S. I'm using browser action to load a local HTML in IFRAME. So I'm not using popup.js.

Karlen Kishmiryan
  • 7,322
  • 5
  • 35
  • 45

2 Answers2

91

localStorage

Pros:

  • Synchronous, and thus easier to work with: var value = localStorage[key]
  • Has support in Dev Tools: Resources > Local Storage to view and modify.

Cons:

  • Only stores strings, therefore you need to serialize data yourself, i.e. with JSON.stringify
  • Is not accessible from content scripts (or rather, context scripts share it with the page and not the extension), so you need to rely on Messaging to pass values to them.
  • Synchronous AND shared between concurrently-executing extension pages, leading to possible synchronization issues.

chrome.storage.local

Pros:

  • Automagically serializes JSON-compatible data, can store non-strings with no additional boilerplate.
  • Fully available within Content Scripts.
  • Supports events that notify about changes: chrome.storage.onChanged
  • With "unlimitedStorage" permission, can hold arbitrarily large amounts of data.

  • Has a nice built-in mechanism for default values:

    chrome.storage.local.get({key: defaultValue}, function(value){/*...*/});
  • Fully supported in Firefox WebExtensions and Edge Extensions.

Cons:

  • Asynchronous, therefore a bit harder to work with:

    chrome.storage.local.get("key", function(value){/* Continue here */});
  • Not visualized in Dev Tools; one needs to call chrome.storage.local.get(null) to get all values or use something like Storage Area Explorer.

chrome.storage.sync

Same as above, but:

Pros:

  • Automatically synced between signed-in Chrome instances, if extensions sync is enabled.

Cons:

  • Inflexible quotas on data size and update frequency.

  • As of 2016-11-06, not yet supported in either Firefox WebExtensions or Edge Extensions, so non-portable.

    Note: storage.sync is now FF WebExtension compatible, though there is no way to make Chrome and FF natively sync between each other.

Xan
  • 74,770
  • 16
  • 179
  • 206
  • 2
    Re Con for localStorage: "...leading to possible synchronization issues." Sync issues in what sense? If you're referring to the availability of `chrome.storage.*.onChanged`, then it would be fair to also include the `window.onstorage` event. There is another con for `chrome.storage`: Once you made a mistake and attempted to store non-JSON data (e.g. DOM objects), then the storage is completely unusable. This is [a bug](https://code.google.com/p/chromium/issues/detail?id=245969) that should not happen and should be fixed, but nevertheless worth mentioning. – Rob W Jun 18 '14 at 09:14
  • @RobW Consider a code that switches flow based upon a value in `localStorage` and then uses the value in the branch. Meanwhile, another extension page changes the value at the same time. It's unclear what happens. – Xan Jun 18 '14 at 09:16
  • @RobW I was trying to test `window.onstorage` just yesterday, and never got it to work. Can you make a fiddle? – Xan Jun 18 '14 at 09:51
  • 1
    The `storage` event is only triggered in *other* windows. E.g. http://jsfiddle.net/g3EVW/1/show/ – Rob W Jun 18 '14 at 09:55
  • 1
    The JSON bug was fixed. – Dan Dascalescu May 27 '15 at 22:32
  • I was wondering if while development is in progress will one see the localstorage key and value when viewing the background.js file in devtools? I'm trying to test setting these and yes I can see the value when I chrome.storage.local.get but aren't these values supposed to display under localstorage? – TikaL13 Jan 25 '16 at 21:03
  • I imagin localStorage is cross browser compatible as well whilst chrome.storage isn't? That would be a pretty big pro / con for me! – RyanfaeScotland Sep 29 '16 at 13:25
  • Well, both Edge and Firefox support `chrome.storage.local` in their extension models. Note we're talking specifically about extensions - it's not exposed to the web. `sync` is not supported (yet) in either. – Xan Sep 29 '16 at 13:26
  • Thanks Xan. Have managed to get a simple extension running in Chrome and FF, hopefully the same codebase will work with Edge. Just IE left and that'll do me! – RyanfaeScotland Oct 02 '16 at 12:37
64

It depends entirely on what your Chrome Extension will be doing. window.localStorage is HTML5 storage. Unless you're running it in the background page, it can only allow you to get and set data into storage for a specific domain. This is also true for code injected into the DOM, since it would use the localStorage on the web page.

In other words, you won't be able to share data across different web pages unless you use localStorage in the background page, which operates independently of web pages, since it has a chrome:// URI as its domain.

chrome.storage.local, on the other hand, is designed for Chrome Extensions and Chrome Apps to store data in a more central location. Since this isn't accessible to normal web pages, each Extension gets its own storage. One possibility is for your background page to handle dealing with the setting and getting of the data, while your content scripts deal with modifying and interacting with the web page.

However, these API's work in content scripts as well, and both of the extensions I've written use chrome.storage.local called from the content scripts.

As an example, I built a Stack App that preserves inbox items in Stack Exchange until you've actually read them, called StackInbox. Since Stack Exchange sites span across hundreds of domains, I chose chrome.storage.local because I could save the user's accountId and reuse it across all the sites, ensuring that the inbox data is synchronized, while also using this directly in the content script.

As a simple test, put some data in localStorage on one domain, in a content script, and try to pull it from another, and you'll see that the data won't be there. With chrome.storage.local, this isn't a problem.

Lastly, Chrome Extensions and Chrome Apps are whitelisted, since the user chose to install it, so they typically can do more things than a normal website. For instance, by specifying the "unlimitedStorage" permission in your manifest, you can store data well beyond the 5MB limit placed upon HTML5 localStorage.

For more information, see Google's documentation on Chrome Storage.

Community
  • 1
  • 1
jamesmortensen
  • 33,636
  • 11
  • 99
  • 120
  • 4
    Right, localStorage is domain dependent, but you can use it in your Chrome extension (e.g. background script or popup script) to store and share data between different web pages because the domain restriction will be bound to the `chrome-extension://` URL of the extension rather than the URL of any web site the extension is running on – devnull69 Jun 18 '14 at 08:28
  • 1
    @devnull69 - Thanks for that correction. I just spent some time playing with this, and sure enough, localStorage is available in the background page. Learn something new everyday. :) – jamesmortensen Jun 18 '14 at 08:57
  • I think this answer is more suitable to my question. Thank you @jmort253. I will definitely use the `chrome.storage`. – Karlen Kishmiryan Jun 18 '14 at 11:38
  • from https://developer.chrome.com/extensions/declare_permissions and https://bugs.chromium.org/p/chromium/issues/detail?id=58985 , it seems that the `unlimitedStorage` doesn’t increase the localStorage capacity. – 张实唯 Dec 15 '17 at 11:18
  • Is Chrome storage truly persistent? Or can the user delete it, like with localStorage? I want something more persistent than localStorage - I want something that only my app can delete, I don't want the user to be able to delete it. – Alexander Mills Jan 29 '18 at 20:49
  • 1
    @AlexanderMills for anything critical, I wouldn't store it locally. Users can, at the time of this writing, pretty much delete whatever they want to delete on their computers. Also, I've seen this storage clear itself out before for reasons which I didn't fully understand. Hope this helps! – jamesmortensen Feb 05 '18 at 05:14
  • Can the user accidentally delete `window.chrome.storage.local` data like they can with `window.localStorage`? – Alexander Mills Feb 23 '18 at 18:14