Storage

TurboStarter leverages @plasmohq/storage library to handle persistent storage for your extension. It's a utility library from 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.

Storing data

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.

TurboStarter ships with predefined storage used to handle theming in your extension, but you can create your own storage as well.

All storage-related methods and types are located in lib/storage directory.

import { Storage } from "@plasmohq/storage";
 
import { appConfig } from "~/config/app";
 
const storage = new Storage();
 
export const THEME_STORAGE_KEY = "theme";
 
export const setupThemeStorage = async () => {
  const value = await storage.get(THEME_STORAGE_KEY);
 
  if (!value) {
    await storage.set(THEME_STORAGE_KEY, appConfig.theme.default);
  }
};

Then, to make it available around your extension, we're calling the setup method in background service worker:

import { setupStorage } from "~/lib/storage";
 
const main = async () => {
  await setupStorage();
};
 
void main();

To learn more about customizing your storage, syncing state or setup automatic backups please refer to the official documentation.

Consuming storage

To consume storage in your extension, you can use the useStorage React hook that is automatically provided to every part of the extension. The hook API is designed to streamline the state-syncing workflow between the different pieces of an extension.

Here is an example on how to consume our theme storage in Layout component:

export const Layout = ({ children }: { children: React.ReactNode }) => {
  const [config] = useStorage<ThemeConfig>(STORAGE_KEY.THEME);
 
  return (
    <div id="root" data-theme={config?.color}>
      {children}
    </div>
  );
};

Congrats! You've just learned how to persist and consume global data in your extension 🎉

For more advanced use cases, please refer to the official documentation.

Usage with Firefox

To use the storage API on Firefox during development you need to add an addon 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

To add an addon ID to your manifest, add this to your package.json:

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

During development, you may use any ID. If you have published your extension, you need to use the ID assigned by Mozilla Addons.