Storage API

@plasmohq/storage is a utility library from plasmo (opens in a new tab) that abstracts the persistent storage API available to browser extensions. It falls back to localStorage when the extension storage API is unavailable, allowing for state sync between extension pages, content scripts, background service workers and web pages.

This library will enable the storage permission automatically if used as a dependencies in a Plasmo framework (opens in a new tab) project

Installation

pnpm install @plasmohq/storage

The package exports the following modules, in both ESM and CJS format:

Usage Examples

• See with-storage (opens in a new tab) for an example of how to use this library to sync state between options and popups.
• See with-redux (opens in a new tab) for an example of how to use this library as your Redux persistent layer (crucial for MV3).
• See MICE (opens in a new tab) for an experimental use case of this library integrated with WebRTC to pipe messages between browsers via an extension.

Storage

The base Storage API is designed to be easy to use. It is usable in every extension runtime such as background service workers, content scripts and extension pages.

Get/set data without the need to JSON.stringify/parse. As long as the data you are storing is serializable (plain object or of primitive type), it can be stored:

import { Storage } from "@plasmohq/storage"
 
const storage = new Storage()
 
await storage.set("key", "value")
const data = await storage.get("key") // "value"
 
await storage.set("capt", { color: "red" })
const data2 = await storage.get("capt") // { color: "red" }

Customizing the storage area

The storage area defaults to "sync", which means the data is synced across all instances of Chrome where the user is logged in.

You can see all of the other possible scopes Plasmo supports in the Chrome Storage API documentation (opens in a new tab).

const storage = new Storage({
  area: "local"
})

Automatically copy data to localStorage

const storage = new Storage({
  copiedKeyList: ["shield-modulation"]
})

The code above will copy the data to Web localStorage when used with content scripts or extension pages.

Watch (for state sync)

To watch for changes when using the Storage API:

import { Storage } from "@plasmohq/storage"
 
const storage = new Storage()
 
await storage.set("serial-number", 47)
await storage.set("make", "plasmo-corp")
 
storage.watch({
  "serial-number": (c) => {
    console.log(c.newValue)
  },
  make: (c) => {
    console.log(c.newValue)
  }
})
 
await storage.set("serial-number", 96)
await storage.set("make", "PlasmoHQ")

This can be used as a layer to communicate messages across your extension. We demonstrate this in the with-redux (opens in a new tab) example.

Secure Storage

The SecureStorage API extends Storage with data encryption and decryption for at-rest cold storage of sensitive keys. It utilizes the Web Crypto SubtleCrypto API (opens in a new tab) which only works in secure contexts (HTTPS).

import { SecureStorage } from "@plasmohq/storage/secure"
 
const storage = new SecureStorage()
 
await storage.setPassword("roosevelt") // The only diff
 
await storage.set("key", "value")
const data = await storage.get("key") // "value"
 
await storage.set("capt", { color: "red" })
const data2 = await storage.get("capt") // { color: "red" }

React Hook API

The hook API is designed to streamline the state-syncing workflow between the different pieces of an extension. There are many ways it can be used, but first and foremost you will want to import the hook into your React component:

import { useStorage } from "@plasmohq/storage/hook"

Watch and render a value

const [hailingFrequency] = useStorage("hailing")
...
{hailingFrequency}

With a custom storage instance

import { Storage } from "@plasmohq/storage"
...
const [hailingFrequency] = useStorage({
  key: "hailing",
  instance: new Storage({
    area: "local"
  })
})

Rendering initial value WITHOUT persisting

"Persisting" means writing into the internal memory.

By not persisting the value, only this specific instance of the hook will render the given initial value when there is no value in storage. Other instances can either show undefined OR specify their own initial value. To elaborate on this:

Given a popup.tsx that sets a static initial value:

const [hailingFrequency, setHailingFrequency] = useStorage("hailing", "42")
...
<input value={hailingFrequency} onChange={(e) =>
  setHailingFrequency(e.target.value)
  }/> // "42"

If we subscribe to this key in content.tsx, we will see it be undefined until setHailingFrequency is called with a defined value:

const [hailingFrequency] = useStorage("hailing")
 
return <p>{hailingFrequency}</p> // undefined

If we subscribe to this key in options.tsx, but with a different static initial value, we will see that value instead:

const [hailingFrequency] = useStorage("hailing", "147")
 
return <p>{hailingFrequency}</p> // "147"

With the above setup, suppose we call setHailingFrequency("8472") in any of the instances above, we will see that all instances will now show "8472" and will now track the value in storage instead of the initial value.

Rendering AND persisting initial value

By using a function instead of a static value, the initial value will be persisted in storage memory. The initialize function has one parameter which is the existing value in storage. If there is no value, it is undefined.

Let's say we have a popup.tsx that initialize the state to "42" if there is nothing in storage:

const [hailingFrequency, setHailingFrequency] = useStorage("hailing", (v) => v === undefined ? "42": v)
...
{hailingFrequency} // "42"

Then, if we make a new hook instance in our content.tsx or options.tsx, we will see the initial value that persisted, without calling setHailingFrequency:

const [hailingFrequency] = useStorage("hailing")
 
return <p>{hailingFrequency}</p> // "42"

Advanced usage

When dealing with form input or real-time input, you might need the following:

const [hailingFrequency, setHailingFrequency, {
  setRenderValue,
  setStoreValue,
  remove
}] = useStorage("hailing")
 
return <>
  <input value={hailingFrequency} onChange={(e) => setRenderValue(e.target.value)}/>
  <button onClick={() => setStoreValue()}>
    Save
  </button>
  <button onClick={() => remove()}>
    Remove
  </button>
</>
 

Usage with Firefox

To use the storage API on Firefox during development you need to add an Add-on ID to your manifest, otherwise, you will get this error:

Error: The storage API will not work with a temporary addon ID. Please add an explicit addon ID to your manifest. For more information see https://mzl.la/3lPk1aE (opens in a new tab).

To add an Add-on ID to your manifest, add this to your package.json:

"manifest": {
  "browser_specific_settings": {
    "gecko": {
      "id": "your-id@example.com"
    }
  }
}

The format of Add-on IDs differ between manifest versions.

• Manifest V2: your-id@example.com
• Manifest V3: {ed7ba470-8e54-465e-825c-99712043e01c} (any UUID)

Once your extension is published, the Add-on ID defined in the package.json file should be displayed in your extension's Developer Page under "Technical Details > UUID".

Note: The Add-on ID used during development (i.e. the one defined in the manifest) will likely be the one Mozilla assigns to your when publishing. If it's not and one is generated for you, you will have to update the package.json file with the new ID.

Add-on IDs are unique and the same one cannot be used for multiple extensions (both manifest versions).