@pinian/persistent-state

This plugin offers effortless state persistence for Pinia stores with a flexible, easy-to-use API. From simple defaults to advanced customizations like multi-storage and serializers, it streamlines state management through a single persistentState option, making it a perfect fit for any project.

Features

• Effortless State Persistence: Automatically saves and loads your store's state, ensuring a seamless experience across sessions and page reloads.
• Flexible Storage Options: Choose between localStorage, sessionStorage, or even define your own custom storage solution to fit your needs.
• Granular Control: Configure persistence for the entire store or fine-tune it to save specific parts of your state with ease.
• XSS Protection: Protect your state from XSS by sanitizing data during both save and load, ensuring only clean information is used.
• Zero Dependencies: This plugin is built with zero external dependencies, ensuring minimal overhead and maximum compatibility with any project setup.

Quick Start

1. Install the plugin:

1npm install @pinian/persistent-state

2. Register the plugin with Pinia:

1import { createPinia } from 'pinia';
2import { createPersistentState } from '@pinian/persistent-state';
3
4const pinia = createPinia();
5pinia.use(createPersistentState());

3. Add the persistentState option to the store you want to be persisted:

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: true,
10});

Your store will be saved using the default configuration.

Configuration

The plugin provides flexible configuration options that can be applied in two main ways:

1. Globally: Set configuration options that apply to all stores during plugin initialization. This is useful when you want consistent behavior across all your stores without repeating configuration.
2. Locally (Per Store): Override global settings or specify custom settings for individual stores by using the persistentState option within the store definition.

Global Configuration

To apply configurations globally, pass them when registering the plugin with Pinia:

1import { createPinia } from 'pinia';
2import { createPersistentStatePlugin } from '@pinian/persistent-state';
3
4const pinia = createPinia();
5pinia.use(createPersistentStatePlugin({
6  auto: true,
7  key: (id) => `v1.0.0-${id}`,
8  storage: localStorage,
9  serialize: (state) => btoa(JSON.stringify(state)),
10  deserialize: (state) => JSON.parse(atob(state)),
11}));

Local Configuration

For specific stores, you can use the persistentState option to override the global settings or define custom behavior. There are three ways to configure persistentState for a store:

1. Boolean (true): Use global defaults to persist the entire store state.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: true,
10});

2. Object: Define custom settings for the store, such as custom keys, specific storage, or choosing paths to persist.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7      password: 'secret',
8    },
9    settings: {
10      theme: 'dark',
11    },
12  }),
13  persistentState: {
14    key: (id) => `v1.0.0-${id}`,
15    storage: localStorage,
16    serialize: (state) => btoa(JSON.stringify(state)),
17    deserialize: (state) => JSON.parse(atob(state)),
18    pickPaths: [
19      'user',
20      'settings',
21    ],
22    omitPaths: [
23      'user.password',
24    ],
25  },
26});

3. Array of Objects: If you need to apply more complex persistence logic, such as storing different parts of the state in different storages, you can use an array of configuration objects.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7      password: 'secret',
8    },
9    settings: {
10      theme: 'dark',
11    },
12  }),
13  persistentState: [
14    {
15      key: (id) => `v1.0.0-${id}`,
16      storage: localStorage,
17      serialize: (state) => btoa(JSON.stringify(state)),
18      deserialize: (state) => JSON.parse(atob(state)),
19      pickPaths: [
20        'user',
21      ],
22      omitPaths: [
23        'user.password',
24      ],
25    },
26    {
27      storage: sessionStorage,
28      serialize: (state) => JSON.stringify(state),
29      deserialize: (state) => JSON.parse(state),
30      pickPaths: [
31        'settings.theme',
32      ]
33    },
34  ],
35});

Options

auto

• type: boolean
• default: false
• scope: Global

Defines whether state persistence should be enabled by default for all stores. This can be useful when you want to save the entire application state to browser storage without explicitly configuring each store.

1import { createPinia } from 'pinia';
2import { createPersistentStatePlugin } from '@pinian/persistent-state';
3
4const pinia = createPinia();
5pinia.use(createPersistentStatePlugin({
6  auto: true,
7}));
8
9export const useStore = defineStore('profile', {
10  state: () => ({
11    user: {
12      name: 'John Doe',
13    },
14  }),
15});

key

• type: (id: string) => string
• default: (id) => id
• scope: Global and Local

Defines a custom key to identify the store's state in the selected storage.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: {
10    key: (id) => `prefix-${id}`,
11  },
12});

storage

• type: KeyValueStorage
• default: localStorage
• scope: Global and Local

Defines which storage mechanism to use. It can be localStorage, sessionStorage, or a custom implementation of the KeyValueStorage interface.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: {
10    storage: sessionStorage,
11  },
12});

serialize

• type: (state: T) => string
• default: JSON.stringify
• scope: Global and Local

Defines how to serialize the state into a string before saving it. You can also provide a custom serialization method if needed.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: {
10    serialize: (state) => btoa(JSON.stringify(state)),
11  },
12});

deserialize

• type: (state: string) => T
• default: JSON.parse
• scope: Global and Local

Defines how to deserialize the string from storage back into the state object. You can also provide a custom deserialization method if needed.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7    },
8  }),
9  persistentState: {
10    deserialize: (state) => JSON.parse(atob(state)),
11  },
12});

pickPaths

• type: string[]
• default: []
• scope: Local

Defines which paths of the state should be saved. You can specify only the paths you want to store.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('profile', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7      password: 'secret',
8    },
9    settings: {
10      theme: 'dark',
11    },
12  }),
13  persist: {
14    pickPaths: [
15      'user.name',
16      'settings.theme',
17    ],
18  },
19});

omitPaths

• type: string[]
• default: []
• scope: Local

Defines which paths of the state should not be saved. All other paths will be stored.

1import { defineStore } from 'pinia';
2
3export const useStore = defineStore('main', {
4  state: () => ({
5    user: {
6      name: 'John Doe',
7      password: 'secret',
8    },
9    settings: {
10      theme: 'dark',
11    },
12  }),
13  persist: {
14    omitPaths: [
15      'user.password',
16    ],
17  },
18});

License

@pinian/persistent-state is released under the MIT License.