pinia-persistence-plugin 
Handle Pinia state persistence easily.
Features
- Support multiple storages.
- Can be configured globally and in every Pinia store.
- Support async storages like localForage.
- Storages, store paths and serialization method can be customized.
Installation
Install with your favorite package manager:
# npm
npm i pinia-persistence-plugin
# yarn
yarn add pinia-persistence-plugin
# pnpm
pnpm add pinia-persistence-plugin
Usage
Add this plugin to your Pinia instance:
import { createPinia } from 'pinia'
import { persistencePlugin } from 'pinia-persistence-plugin'
const pinia = createPinia()
pinia.use(persistencePlugin())
The persistence is enabled by default for all pinia stores and the default storage is localStorage.
Configuration
Plugin Options
persistencePlugin({
// plugin options goes here
storeKeysPrefix: 'test',
persistenceDefault: false,
storageItemsDefault: [
{
storage: sessionStorage,
},
],
debug: true,
})
-
storeKeysPrefix?: string: Defaults to undefined. Add prefix to stores keys.
-
persistenceDefault?: boolean: Defaults to true. Whether to persist all stores by default.
-
storageItemsDefault?: PluginStorageItem[]: Defaults to localStorage. List of storages.
-
assertStorage?: (storage: Storage) => void | Promise<void>: Perform a write and delete operation by default. To ensure storages is available.
-
ensureAsyncStorageUpdateOrder?: boolean: Ensure that the update of asynchronous storages is done in order
-
debug?: boolean: Defaults to false. Display errors and warnings in console.
PluginStorageItem
-
storage?: Storage: Where to store persisted state
-
includePaths?: string[]: Defaults to []. An array of any paths to partially persist the state
-
excludePaths?: string[]: Defaults to []. An array of any paths to exclude
-
serializer?: Serializer: Object containing serialize and deserialize methods
-
serialize?: (state: S): any: Defaults to JSON.stringify. This method will be called right before storage.setItem.
-
deserialize?: (value: any): any: Defaults to JSON.parse. This method will be called right after storage.getItem.
Store Options
defineStore(
'store',
() => {
const count = ref(0)
const increment = () => count.value++
return {
count,
increment,
}
},
{
persistence: {
// store options goes here
enabled: true,
storageItems: [
{
key: 'sample',
storage: sessionStorage,
includePaths: ['count'],
},
],
},
}
)
enabled?: boolean: Enable persistence for the storestorageItems?: StorageItem[]: List of storages.beforeHydrate?: (oldState: S) => void: Perform some tasks before patching the store
StorageItem
key?: string: Defaults to store.$id. The persisted store state key.
And the same properties as PluginStorageItem
Storage
-
getItem: (key: string) => any | Promise<any>
-
setItem: (key: string, value: any) => void | Promise<void>
-
removeItem: (key: string) => void | Promise<void>
Some examples of use
js-cookie
import { defineStore } from 'pinia'
import Cookies from 'js-cookie'
defineStore('example', {
// ...
persistence: {
enabled: true,
storageItems: [
{
storage: {
getItem: (key: string) => {
return Cookies.get(key)
},
setItem: (key: string, value: any) => {
Cookies.set(key, value)
},
removeItem: (key: string) => {
Cookies.remove(key)
},
},
},
],
},
})
localForage
import { defineStore } from 'pinia'
import localforage from 'localforage'
localforage.config({
driver: [localforage.INDEXEDDB],
name: 'Test IndexedDB',
storeName: 'store',
})
defineStore('example', {
// ...
persistence: {
enabled: true,
storageItems: [
{
storage: {
getItem: async (key: string) => {
return await localforage.getItem(key)
},
setItem: async (key: string, value: any) => {
await localforage.setItem(key, value)
},
removeItem: async (key: string) => {
await localforage.removeItem(key)
},
},
},
],
},
})
Custom serialize method
import { defineStore } from 'pinia'
import stringify from 'json-stringify-safe'
defineStore('example', {
// ...
persistence: {
enabled: true,
storageItems: [
{
storage: localStorage,
serializer: {
serialize: (value: any) => stringify(value),
},
},
],
},
})
localStorage with SecureLS encryption
import { defineStore } from 'pinia'
import SecureLS from 'secure-ls'
var ls = new SecureLS({
encodingType: 'aes',
isCompression: false,
})
defineStore('example', {
// ...
persistence: {
enabled: true,
storageItems: [
{
key: 'encrypted_data',
storage: {
getItem: (key: string) => {
try {
return ls.get(key)
} catch (error) {
console.error(error)
}
},
setItem: (key: string, value: any) => {
try {
ls.set(key, value)
} catch (error) {
console.error(error)
}
},
removeItem: (key: string) => {
try {
ls.remove(key)
} catch (error) {
console.error(error)
}
},
},
},
],
},
})
You can see an example of a full implementation here here
This project is inspired by vuex-persistedstate and pinia-plugin-persist.
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Changelog
Detailed changes for each release are documented in the release notes.
License
This project is under MIT license.
