WXT

Appearance

API > wxt/utils/storage > WxtStorageItemOptions

Interface: WxtStorageItemOptions<T, TRaw, TVersion> ​

Contents ​

Type parameters ​

▪ T

▪ TRaw = unknown

▪ TVersion extends number = number

Properties ​

debug ​

debug?: boolean

Print debug logs, such as migration process.

Default ​

ts
false

Source ​

packages/storage/dist/index.d.mts:192

defaultValue ​

defaultValue?: DeepReadonly<T>

Deprecated ​

Renamed to fallback, use it instead.

Accepts a deep-readonly variant so narrow readonly literals produced by <const> inference (e.g. { label: 'Default' as const }) flow through without a cast at the call site.

Source ​

packages/storage/dist/index.d.mts:141

fallback ​

fallback?: DeepReadonly<T>

Default value returned when getValue would otherwise return null.

Accepts a deep-readonly variant — see defaultValue comment above.

Source ​

packages/storage/dist/index.d.mts:147

init ​

init?: () => T | Promise<T>

If passed, a value in storage will be initialized immediately after defining the storage item. This function returns the value that will be saved to storage during the initialization process if a value doesn't already exist.

Source ​

packages/storage/dist/index.d.mts:154

migrations ​

migrations?: MigrationTuple<TVersion>

Chain of migration functions applied to previously-stored values on read. Ordered by target version: position i migrates from version i + 1 to `i

  • 2. migrations: [v1to2, v2to3]paired withversion: 3` means v1 storage runs both, v2 storage runs only the second, v3 runs nothing.

Use defineMigrations<TValue>() for chain-checked typing where each migration's return type is verified against the next fn's parameter and the final return is verified against TValue.

Note: the parameter type is any, not unknown. Intentional — each position accepts a different type (v1 raw at position 0, then previous fn's return type). unknown in a contravariant position would reject narrow-param fns produced by defineMigrations.

Source ​

packages/storage/dist/index.d.mts:186

onMigrationComplete ​

onMigrationComplete?: (migratedValue, targetVersion) => void

A callback function that runs on migration complete.

Parameters ​

▪ migratedValue: T

▪ targetVersion: TVersion

Source ​

packages/storage/dist/index.d.mts:194

onValidationError ​

onValidationError?: OnValidationError<T>

How to handle a schema failure when reading a value from storage. Writes always throw on schema failure; this option only affects reads and watch() callbacks.

  • 'throw' (default): throw a SchemaError containing the issues.
  • 'fallback': return fallback (or null if no fallback is set).
  • 'reset': clear the invalid value from storage and return fallback.
  • (issues, raw) => T: custom recovery — the returned value becomes the read result. The value is not written back to storage.

Default ​

ts
'throw'

Source ​

packages/storage/dist/index.d.mts:255

schema ​

schema?: StandardSchemaV1<unknown, T>

A Standard Schema validator applied to the deserialized runtime value on read, and to the input value on write.

Pipeline:

  • Read: raw → migrate → serializer.read? → schema.validate → T
  • Write: T → schema.validate → serializer.write? → raw

Any Standard Schema-conformant validator works: Zod, Valibot, ArkType, Effect Schema. For TypeBox, io-ts, or custom parsers, wrap them with defineSchema().

Example ​

ts
  import { z } from 'zod';
  const theme = storage.defineItem('local:theme', {
    schema: z.enum(['light', 'dark', 'system']),
  });
  ```;

#### Source

packages/storage/dist/index.d.mts:216

***

### serializer

> **serializer**?: [`WxtStorageItemSerializer`](WxtStorageItemSerializer.md)\<`T`, `TRaw`\>

Convert between the runtime type `T` and the wire form stored in
`chrome.storage`. `write` is required; `read` is optional — omit when a
coerce schema handles deserialization (e.g. `z.coerce.date()`).

Naming mirrors VueUse's `useStorage` serializer.

#### Example

```ts
  // Sets aren't JSON-serializable — hand-write both directions.
  storage.defineItem('local:enabled-sites', {
  serializer: {
  write: (set: Set<string>) => [...set],
  read: (raw) => new Set(Array.isArray(raw) ? raw.filter((x): x is string => typeof x === 'string') : []),
  },
  });

  // Storing a Date with a coerce schema: only `write` needed.
  storage.defineItem('local:install-date', {
  serializer: { write: (d: Date) => d.toISOString() },
  schema: z.coerce.date(),
  });

Source ​

packages/storage/dist/index.d.mts:241

version ​

version?: TVersion

Provide a version number for the storage item to enable migrations. When changing the version in the future, migration functions will be ran on application startup.

When passed as a numeric literal (version: 3) TypeScript captures it as the literal type 3 via the <const TVersion extends number> modifier on defineItem, which:

  1. Length-locks the migrations tuple below to exactly TVersion - 1 entries. Mismatched counts become compile-time errors.
  2. Narrows WxtStorageItem['version'] to the literal for typed introspection.

Source ​

packages/storage/dist/index.d.mts:168

Generated using typedoc-plugin-markdown and TypeDoc