Configuration

The plugin comes pre-configured with the following:

localStorage as storage.
store.$id as default key for storage.
JSON.stringify/JSON.parse as serializer/deserializer.
The whole state is persisted to the storage.

However, you can pass an object to the persist property of the store to configure the persistence.

import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    // CONFIG OPTIONS HERE
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    // CONFIG OPTIONS HERE
  },
})

key

type: string
default: store.$id

Key used to reference the stored deserialized data in the storage.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    key: 'my-custom-key',
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    key: 'my-custom-key',
  },
})

This store will be persisted under the my-custom-key key in localStorage.

storage

type: StorageLike
default: localStorage

Storage to persist the data to. Must have getItem: (key: string) => string | null and setItem: (key: string, value: string) => void methods.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    storage: sessionStorage,
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    storage: sessionStorage,
  },
})

This store will be persisted in sessionStorage.

WARNING

Storage must be synchronous. More info in the limitations page.

paths

type: string[]
default: undefined

Array of dot-notation paths to partially persist state. [] means no state is persisted and undefined or null means the whole state is persisted.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    save: {
      me: 'saved',
      notMe: 'not-saved',
    },
    saveMeToo: 'saved',
  }),
  persist: {
    paths: ['save.me', 'saveMeToo'],
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    save: {
      me: 'saved',
      notMe: 'not-saved',
    },
    saveMeToo: 'saved',
  }),
  persist: {
    paths: ['save.me', 'saveMeToo'],
  },
})

In this store, only save.me and saveMeToo values will be persisted. save.notMe will not be persisted.

To store all elements of an array, use the notation '[]'.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    save: [
      { me: 'saved', ignored: 'ignored' },
      { me: 'saved-too', value: 'ignored-too' },
      { me: 'saved-as-well', test: 'ignored-as-well' },
    ],
  }),
  persist: {
    paths: ['save.[].me'],
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    save: [
      { me: 'saved', ignored: 'ignored' },
      { me: 'saved-too', value: 'ignored-too' },
      { me: 'saved-as-well', test: 'ignored-as-well' },
    ],
  }),
  persist: {
    paths: ['save.[].me'],
  },
})

In this store, only save[0].me, save[1].me and save[2].me values will be persisted.

serializer

type: Serializer
default: JSON.stringify/JSON.parse

Custom serializer to serialize data before persisted and deserialize data before rehydrating the store. Must have serialize: (value: StateTree) => string and deserialize: (value: string) => StateTree methods.

Example

import { defineStore } from 'pinia'
import { stringify, parse } from 'zipson'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    serializer: {
      deserialize: parse,
      serialize: stringify
    }
  },
})

import { defineStore } from 'pinia'
import { stringify, parse } from 'zipson'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    serializer: {
      deserialize: parse,
      serialize: stringify
    }
  },
})

This store will use zipson's stringify/parse to handle serialization/deserialization with added compression.

beforeRestore

type: (context: PiniaPluginContext) => void
default: undefined

Hook function run before restoring a persisted state. The hook gives access to the whole PiniaPluginContext. This can be used to enforce specific actions before hydration.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    beforeRestore: (ctx) => {
      console.log(`about to restore '${ctx.store.$id}'`)
    }
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    beforeRestore: (ctx) => {
      console.log(`about to restore '${ctx.store.$id}'`)
    }
  },
})

This store will log about to restore 'store' before being rehydrated.

WARNING

Beware of interacting with PiniaPluginContext, unexpected behaviors may occur.

afterRestore

type: (context: PiniaPluginContext) => void
default: undefined

Hook function run after restoring a persisted state. The hook gives access to the whole PiniaPluginContext. This can be used to enforce specific actions after hydration.

Example

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    afterRestore: (ctx) => {
      console.log(`just restored '${ctx.store.$id}'`)
    }
  },
})

import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    afterRestore: (ctx) => {
      console.log(`just restored '${ctx.store.$id}'`)
    }
  },
})

This store will log just restored 'store' after being rehydrated.

WARNING

Beware of interacting with PiniaPluginContext, unexpected behaviors may occur.

debug

type: boolean
default: false

When set to true, any error that may occur while persisting/hydrating stores will be logged as console.error.

Configuration #

key #

storage #

paths #

serializer #

beforeRestore #

afterRestore #

debug #

Configuration

key

storage

paths

serializer

beforeRestore

afterRestore

debug