• Browser Extension API
  • Storage


See LicenseNPM InstallFollow PlasmoHQ on TwitterWatch our Live DEMO every FridayJoin our Discord for support and chat about our projects

@plasmohq/storage is a utility library from plasmo 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 popup - options - contents - background.

This library will enable the storage permission automatically if used with the Plasmo framework


pnpm install @plasmohq/storage

Usage Examples

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

Storage API (for content scripts or background workers)

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

Customizing the storage area

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

Preventing data from being mirrored into localStorage

const storage = new Storage({
  secretKeyList: ["shield-modulation"]

The code above prevents data from being leaked into localStorage when used with content scripts. This setting is recommended if you are storing JWT access token to invoke your server-side API.

Watch API (for state sync)

The Hook API automatically watches for new changes.

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")
  "serial-number": (c) => {
  make: (c) => {
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 example.

Hook API (for react components - i.e popup, options, content-script-ui)

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

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

Watch and render a value in storage:

const [hailingFrequency] = useStorage("hailing")

Specifying the storage area:

const [hailingFrequency] = useStorage({
  key: "hailing",
  area: "local"

Specifying an initial value for rendering 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")
return <input value={hailingFrequency} onChange={(e) => setHailingFrequency(e.target.value)}/> // "42"

If we subscribe to this key in a content.tsx script, 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 an 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 instance will now show "8472" and will now track the value in storage instead of initial value.

Specifying an initial value AND persisting it:

By using a function instead of a static value, the initial value will be persisted into 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", async (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 was persisted, without calling setHailingFrequency:

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

Advanced Hook API usage

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

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