Artwork from Pinia

pinia-plugin-persistedstate

Configurable persistence and rehydration of Pinia stores.

✨ Features

Persist Pinia stores with the same API as vuex-persistedstate (and more).
Configurable per Pinia store.
Still compatible with Vue 2 and 3.
No external dependencies.
Supports a custom serializer for advanced needs.
Super small (<1kB).

⚙️ Installing

Install with your favorite package manager:
- pnpm : pnpm i pinia-plugin-persistedstate
- npm : npm i pinia-plugin-persistedstate
- yarn : yarn add pinia-plugin-persistedstate
Add the plugin to pinia:

import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

🚀 Usage

You just need to add the persist option to the store you want to be persisted as follows:

import { defineStore } from 'pinia'

//* using option store syntax
export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    }
  },
  persist: true,
})

//* or using setup store syntax
export const useStore = defineStore(
  'main',
  () => {
    const someState = ref('hello pinia')
    return { someState }
  },
  {
    persist: true,
  },
)

In case you want to configure how the data should be persisted, persist can take options:

key: string : Key to use in storage (defaults to the current store id).
storage : Storage like object to persist state to. Must have getItem and setItem methods (defaults to localStorage).
paths: Array<string> : Array of dot-notation paths to partially persist the state, [] means no state is persisted (defaults to undefined and persists the whole state).
beforeRestore: (context) => void : Hook executed (if set) before restoring the state from local storage.
afterRestore: (context) => void : Hook executed (if set) after restoring the state from local storage.

The context passed to the hooks is the PiniaPluginContext. It exposes properties such as the current store. More infos here.

serializer: { serialize, deserialize } : Custom serializer/deserializer :
- serialize: (state) => string : Function to serialize the state before storing (defaults to JSON.stringify).
- deserialize: (string) => state : Function to deserialize the stored stated before rehydrating (defaults to JSON.parse).

The state used in serialize and deserialize is the generic state of the current store. More infos here.

import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
      nested: {
        data: 'nested pinia',
      },
    }
  },
  persist: {
    key: 'store-key',
    storage: window.sessionStorage,
    paths: ['nested.data'],
    beforeRestore: context => {
      console.log('Before hydration...')
    },
    afterRestore: context => {
      console.log('After hydration...')
    },
  },
})

The config above will only persist the nested.data property in sessionStorage under store-key.

It will also execute the beforeRestore and afterRestore hooks respectively before and after hydration.

Usage with Nuxt

Declare a Nuxt Plugin to add the plugin to Pinia.

import { createNuxtPersistedState } from 'pinia-plugin-persistedstate'
import { defineNuxtPlugin, useCookie } from '#app'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.$pinia.use(createNuxtPersistedState(useCookie))
})

The plugin will use Nuxt's Cookies and useCookie to define a storage to persist your stores with SSR.

import { defineStore } from 'pinia'

export const useUserStore = defineStore('ssr', {
  persist: true
})

Warning: when using createNuxtPersistedState, overriding the storage option in the store definition will break server-side persistance/rehydration with Cookies.

🔧 Factory function configuration

Need to override default options? You can import and use createPersistedState(options):

import { createPinia } from 'pinia'
import { createPersistedState } from 'pinia-plugin-persistedstate'
const pinia = createPinia()
pinia.use(createPersistedState({
  storage: sessionStorage,
  beforeRestore: () => {},
  afterRestore: () => {},
  serializer: {
    serialize: JSON.stringify,
    deserialize: JSON.parse,
  }
}))

The options passed will be used in any store declaring persist: true. You can still override these defaults with per-store options.

You can also override default options in Nuxt with createNuxtPersistedState(useCookie, options).

⚠️ Limitations

References do not persist

Beware of the following:

const a = {
  1: 'one',
  2: 'two',
  ...
}
const b = a

// Before hydration 'a' and 'b'
// point to the same object:
a === b -> true

// After hydration (page reload)
// 'a' and 'b' are different objects
// with the same content:
a === b -> false

As a consequence, reactivity between a and b is lost.

To get around this you can exclude either a or b from persisting and use the afterRestore hook to populate them after hydration. That way a and b have the same reference again and reactivity is restored after page reload.

Non primitive types are not persisted

Due to serialization (JSON.stringify/JSON.parse) needed to persist in storage, non primitive typed data such as Date are no rehydrated as Date but as string instead.

To get around this you can use the afterRestore hook to reformat the data as needed.

Storage must be synchronous

When providing a storage option, all methods (getItem, setItem) must be synchronous. This is due to Pinia's state subscription ($subscribe) being synchronous (like mutations).

If you want to add asynchronous behavior (such as async storages), you can try subscribing to actions ($onAction). Actions are made for asynchronous tasks and provide proper error handling.

🤝 Contributing

This project tries to bring vuex-persistedstate's API to Pinia but I did not bring the whole API yet.

Run into a problem? Open an issue. Want to add some feature? PRs are welcome!

👤 About the author

Feel free to contact me:

jopicornell/pinia-plugin-persistedstate