pinia-plugin-persistedstate

What is pinia-plugin-persistedstate?

The pinia-plugin-persistedstate npm package is a plugin for Pinia, a state management library for Vue.js. This plugin allows you to persist and rehydrate the state of your Pinia stores using various storage mechanisms like localStorage, sessionStorage, or custom storage solutions.

What are pinia-plugin-persistedstate's main functionalities?

Persist State to localStorage

This feature allows you to persist the state of your Pinia store to localStorage. By setting `persist: true` in your store definition, the state will be automatically saved to localStorage and rehydrated when the application is reloaded.

{"import":"import { createPinia } from 'pinia';\nimport piniaPluginPersistedstate from 'pinia-plugin-persistedstate';\n\nconst pinia = createPinia();\npinia.use(piniaPluginPersistedstate);","store":"import { defineStore } from 'pinia';\n\nexport const useMainStore = defineStore('main', {\n  state: () => ({\n    counter: 0\n  }),\n  persist: true\n});"}

Custom Storage

This feature allows you to use a custom storage mechanism for persisting the state. In this example, the state is persisted to sessionStorage instead of localStorage by providing a custom storage object.

{"import":"import { createPinia } from 'pinia';\nimport piniaPluginPersistedstate from 'pinia-plugin-persistedstate';\n\nconst pinia = createPinia();\npinia.use(piniaPluginPersistedstate);","store":"import { defineStore } from 'pinia';\n\nconst customStorage = {\n  getItem: (key) => window.sessionStorage.getItem(key),\n  setItem: (key, value) => window.sessionStorage.setItem(key, value),\n  removeItem: (key) => window.sessionStorage.removeItem(key)\n};\n\nexport const useMainStore = defineStore('main', {\n  state: () => ({\n    counter: 0\n  }),\n  persist: {\n    storage: customStorage\n  }\n});"}

Partial State Persistence

This feature allows you to persist only specific parts of the state. In this example, only the `counter` state is persisted, while the `user` state is not.

{"import":"import { createPinia } from 'pinia';\nimport piniaPluginPersistedstate from 'pinia-plugin-persistedstate';\n\nconst pinia = createPinia();\npinia.use(piniaPluginPersistedstate);","store":"import { defineStore } from 'pinia';\n\nexport const useMainStore = defineStore('main', {\n  state: () => ({\n    counter: 0,\n    user: {\n      name: '',\n      email: ''\n    }\n  }),\n  persist: {\n    paths: ['counter']\n  }\n});"}

Other packages similar to pinia-plugin-persistedstate

vuex-persistedstate

vuex-persistedstate is a similar package for Vuex, the state management library for Vue.js. It allows you to persist and rehydrate Vuex state using localStorage, sessionStorage, or custom storage solutions. Compared to pinia-plugin-persistedstate, it is designed specifically for Vuex rather than Pinia.

redux-persist

redux-persist is a package for persisting and rehydrating Redux state. It supports various storage mechanisms and provides advanced features like transforms and migrations. While it is designed for Redux, it offers similar functionality to pinia-plugin-persistedstate for persisting state.

mobx-persist

mobx-persist is a package for persisting and rehydrating MobX state. It supports localStorage and sessionStorage and allows for custom serialization. This package is similar to pinia-plugin-persistedstate but is designed for MobX state management.

README

Pinia Plugin Persistedstate

Configurable persistence and rehydration of Pinia stores.

Documentation

Features

• Persist Pinia stores with a friendly API inspired by vuex-persistedstate.
• Highly customizable (storage, serializer, paths picking/omitting).
• Out of the box SSR-friendly support for Nuxt.
• Very smol (<2kB minzipped).

Quickstart

1. Install with your favorite package manager:

   • pnpm : pnpm add pinia-plugin-persistedstate
   • npm : npm i pinia-plugin-persistedstate
   • yarn : yarn add pinia-plugin-persistedstate

2. Add the plugin to pinia:

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

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

1. Add the persist option to the store you want to be persisted:

import { defineStore } from 'pinia'

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

Configuration

You can configure how a store is persisted by specifying options to the persist property:

export const useStore = defineStore('store', () => {
  const someState = ref('hello pinia')
  return { someState }
}, {
  persist: {
    storage: sessionStorage,
    pick: ['someState'],
  },
})

All the available configuration options are explained here.

Usage with Nuxt

Nuxt support comes out of the box thanks to the included module. You just need to install the package and add the module to your nuxt.config.ts as follows:

export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt', // required
    'pinia-plugin-persistedstate/nuxt',
  ],
})

More information on storages and configuration in Nuxt here.

Limitations

There are several limitations that should be considered, more on those here.

Contributing

See the contribution guide.

License

MIT © 2021-present Sacha Bouillez

Changelog

v4.2.0

compare changes

🚀 Enhancements

• nuxt: Infer global cookieOptions to specified cookie storage without options (3c55848)
• nuxt: Explicit Nuxt plugin name (pinia-plugin-persistedstate) (a0a4c51)

🩹 Fixes

• nuxt: Check @pinia/nuxt module installation by pinia key (#359)

🏡 Chore

• Bump dependencies (incl. pinia^2.3.0 & @pinia/nuxt^0.9.0) (c71d618)

❤️ Contributors

• Prazdevs (@prazdevs)
• Donald Shtjefni (@dnldsht)