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.
Super small (<1kB).

⚙️ Installing

Install with your favourite package manager (pnpm, npm, yarn).
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 localstorage.
afterRestore: (context) => void : Hook executed (if set) after restoring the state from localstorage.

The context passed to the hooks is the PiniaPluginContext. It exposes properties such as 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: 'storekey',
    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 storekey.

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 PiniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import { defineNuxtPlugin } from '#app'

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

You can 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: {
    storage: {
      getItem: (key) => { return useCookie(key, { encode: x => x, decode: x => x }).value },
      setItem: (key, value) => { useCookie(key, { encode: x => x, decode: x => x }).value = value },
    },
  },
})

⚠️ 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 behaviours (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:

isboyjc/pinia-plugin-persistedstate