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
  },
})

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',
  },
})

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,
  },
})

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'],
  },
})

In this store, only save.me and saveMeToo values will be persisted. save.notMe will not 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 { parse, stringify } 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}'`)
    }
  },
})

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}'`)
    }
  },
})

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.