Storage #

Overview #

@webext-core/storage provides a localStorage-like API for interacting with extension storage.

const { key: value } = await browser.storage.local.get('key');
// VS
const value = await localExtStorage.getItem('key');

Installation #

Bundler #

pnpm i @webext-core/storage

import { localExtStorage } from '@webext-core/storage';

const value = await localExtStorage.getItem('key');
await localExtStorage.setItem('key', 123);

Vanilla #

curl -o storage.js https://cdn.jsdelivr.net/npm/@webext-core/storage/lib/index.global.js

<script src="/storage.js"></script>
<script>
  const { localExtStorage } = webExtCoreStorage;

  const value = await localExtStorage.getItem('key');
  await localExtStorage.setItem('key', 123);
</script>

Differences with localStorage and browser.storage #

It's async #

• localStorage uses synchronous APIs
• browser.storage uses asynchronous APIs
• @webext-core/storage uses asynchronous APIs, same as browser.storage

localStorage.getItem('key');

await browser.storage.local.get('key');

await localExtStorage.getItem('key');

Values are stored as-is #

• localStorage can only save strings. You have to manually convert values to and from strings.
• browser.storage stores values without having to convert to and from a string.
• @webext-core/storage stores values without having to convert to and from a string, same as browser.storage

localStorage.setItem('key', JSON.stringify({ property1: false, property2: 1 }));
const itemStr = localStorage.getItem('key');
const item = itemStr == null ? null : JSON.parse(itemStr);

await browser.storage.local.set({
  key: { property1: false, property2: 1 },
}));
const { key: item } = await browser.storage.local.get('key');

await localExtStorage.setItem('key', { property1: false, property2: 1 });
const item = await localExtStorage.getItem('key');

Setting key to undefined #

• localStorage will return null after setting a key to undefined
• browser.storage will return the previous value after setting a key to undefined, undefined values are ignored.
• @webext-core/storage will return null after setting a key to undefined, same as localStorage.

await browser.storage.local.set({ key: 'some-value' });
await browser.storage.local.set({ key: undefined });
const { key: value } = await browser.storage.local.get('key');

console.log(value); // "some-value"

localStorage.setItem('key', 'some-value');
localStorage.setItem('key', undefined);
const value = localStorage.getItem('key');

console.log(value); // null

await localExtStorage.setItem('key', 'some-value');
await localExtStorage.setItem('key', undefined);
const value = await localExtStorage.getItem('key');

console.log(value); // null