Storage API

WXT provides a simplified API to replace the browser.storage.* APIs. Use the storage auto-import from wxt/storage or import it manually to get started:

import { storage } from 'wxt/storage';

WARNING

To use the wxt/storage API, the "storage" permission must be added to the manifest:

// wxt.config.ts
export default defineConfig({
  manifest: {
    permissions: ['storage'],
  },
});

More info on permissions here.

Basic Usage

All storage keys must be prefixed by their storage area.

// ❌ This will throw an error
await storage.getItem('installDate');

// ✅ This is good
await storage.getItem('local:installDate');

You can use local:, session:, sync:, or managed:.

If you use TypeScript, you can add a type parameter to most methods to specify the expected type of the key's value:

await storage.getItem<number>('local:installDate');
await storage.watch<number>(
  'local:installDate',
  (newInstallDate, oldInstallDate) => {
    // ...
  },
);
await storage.getMeta<{ v: number }>('local:installDate');

For a full list of methods available, see the API reference.

Watchers

To listen for storage changes, use the storage.watch function. It lets you setup a listener for a single key:

const unwatch = storage.watch<number>('local:counter', (newCount, oldCount) => {
  console.log('Count changed:', { newCount, oldCount });
});

To remove the listener, call the returned unwatch function:

const unwatch = storage.watch(...);

// Some time later...
unwatch();

Metadata

wxt/storage also supports setting metadata for keys, stored at key + "$". Metadata is a collection of properties associated with a key. It might be a version number, last modified date, etc.

Other than versioning, you are responsible for managing a field's metadata:

await Promise.all([
  storage.setItem('local:preference', true),
  storage.setMeta('local:preference', { lastModified: Date.now() }),
]);

When setting different properties of metadata from multiple calls, the properties are combined instead of overwritten:

await storage.setMeta('local:preference', { lastModified: Date.now() });
await storage.setMeta('local:preference', { v: 2 });

await storage.getMeta('local:preference'); // { v: 2, lastModified: 1703690746007 }

You can remove all metadata associated with a key, or just specific properties:

// Remove all properties
await storage.removeMeta('local:preference');

// Remove one property
await storage.removeMeta('local:preference', 'lastModified');

// Remove multiple properties
await storage.removeMeta('local:preference', ['lastModified', 'v']);

Defining Storage Items

Writing the key and type parameter for the same key over and over again can be annoying. As an alternative, you can use storage.defineItem to create a "storage item".

Storage items contain the same APIs as the storage variable, but you can configure its type, default value, and more in a single place:

// utils/storage.ts
const showChangelogOnUpdate = storage.defineItem<boolean>(
  'local:showChangelogOnUpdate',
  {
    fallback: true,
  },
);

Now, instead of using the storage variable, you can use the helper functions on the storage item you created:

await showChangelogOnUpdate.getValue();
await showChangelogOnUpdate.setValue(false);
await showChangelogOnUpdate.removeValue();
const unwatch = showChangelogOnUpdate.watch((newValue) => {
  // ...
});

For a full list of properties and methods available, see the API reference.

Versioning

You can add versioning to storage items if you expect them to grow or change over time. When defining the first version of an item, start with version 1.

For example, consider a storage item that stores a list of websites that are ignored by an extension.

v1v2v3

type IgnoredWebsiteV1 = string;

export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>(
  'local:ignoredWebsites',
  {
    fallback: [],
    version: 1,
  },
);

import { nanoid } from 'nanoid'; 

type IgnoredWebsiteV1 = string;
interface IgnoredWebsiteV2 { 
  id: string; 
  website: string; 
} 

export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>( 
export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( 
  'local:ignoredWebsites',
  {
    fallback: [],
    version: 1, 
    version: 2, 
    migrations: { 
      // Ran when migrating from v1 to v2
      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { 
        return websites.map((website) => ({ id: nanoid(), website })); 
      }, 
    }, 
  },
);

import { nanoid } from 'nanoid';

type IgnoredWebsiteV1 = string;
interface IgnoredWebsiteV2 {
  id: string;
  website: string;
}
interface IgnoredWebsiteV3 { 
  id: string; 
  website: string; 
  enabled: boolean; 
} 

export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( 
export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV3[]>( 
  'local:ignoredWebsites',
  {
    fallback: [],
    version: 2, 
    version: 3, 
    migrations: {
      // Ran when migrating from v1 to v2
      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => {
        return websites.map((website) => ({ id: nanoid(), website }));
      },
      // Ran when migrating from v2 to v3
      3: (websites: IgnoredWebsiteV2[]): IgnoredWebsiteV3[] => { 
        return websites.map((website) => ({ ...website, enabled: true })); 
      }, 
    },
  },
);

INFO

Internally, this uses a metadata property called v to track the value's current version.

In this case, we thought that the ignored website list might change in the future, and were able to setup a versioned storage item from the start.

Realistically, you won't know a item needs versioned until you need to change it's schema. Thankfully, it's simple to add versioning to an unversioned storage item.

When a previous version isn't found, WXT assumes the version was 1. That means you just need to set version: 2 and add a migration for 2, and it will just work!

Lets look at the same ignored websites example from before, but start with an unversioned item this time:

Unversionedv2

export const ignoredWebsites = storage.defineItem<string[]>(
  'local:ignoredWebsites',
  {
    fallback: [],
  },
);

import { nanoid } from 'nanoid'; 

// Retroactively add a type for the first version
type IgnoredWebsiteV1 = string; 
interface IgnoredWebsiteV2 { 
  id: string; 
  website: string; 
} 

export const ignoredWebsites = storage.defineItem<string[]>( 
export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( 
  'local:ignoredWebsites',
  {
    fallback: [],
    version: 2, 
    migrations: { 
      // Ran when migrating from v1 to v2
      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { 
        return websites.map((website) => ({ id: nanoid(), website })); 
      }, 
    }, 
  },
);

Running Migrations

As soon as storage.defineItem is called, WXT checks if migrations need to be ran, and if so, runs them. Calls to get or update the storage item's value or metadata (getValue, setValue, removeValue, getMeta, etc) will automatically wait for the migration process to finish before actually reading or writing values.

Default Values

With storage.defineItem, there are multiple ways of defining default values:

fallback - Return this value from getValue instead of null if the value is missing.

This option is great for providing default values for settings:

const theme = storage.defineItem('local:theme', {
  fallback: 'dark',
});
const allowEditing = storage.defineItem('local:allow-editing', {
  fallback: true,
});

init - Initialize and save a value in storage if it is not already saved.

This is great for values that need to be initialized or set once:

const userId = storage.defineItem('local:user-id', {
  init: () => globalThis.crypto.randomUUID(),
});
const installDate = storage.defineItem('local:install-date', {
  init: () => new Date().getTime(),
});

The value is initialized in storage immediately.

Storage API ​

Basic Usage ​

Watchers ​

Metadata ​

Defining Storage Items ​

Versioning ​

Running Migrations ​

Default Values ​