0
# Pinia Plugin Persistedstate
1

2
Pinia Plugin Persistedstate provides configurable persistence and rehydration of Pinia stores in Vue.js applications. It offers a friendly API inspired by vuex-persistedstate with highly customizable options including storage backends, serialization methods, and selective state picking/omitting. The plugin features out-of-the-box SSR-friendly support for Nuxt applications and maintains a very small bundle size (<2kB minzipped).
3

4
## Package Information
5

6
- **Package Name**: pinia-plugin-persistedstate
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pinia-plugin-persistedstate`
10

11
## Core Imports
12

13
```typescript
14
import piniaPluginPersistedstate, { 
15
  createPersistedState,
16
  type PluginOptions,
17
  type PersistenceOptions,
18
  type Serializer,
19
  type StorageLike
20
} from "pinia-plugin-persistedstate";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const piniaPluginPersistedstate = require("pinia-plugin-persistedstate");
27
const { createPersistedState } = require("pinia-plugin-persistedstate");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { createPinia } from 'pinia';
34
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
35

36
// Add plugin to Pinia
37
const pinia = createPinia();
38
pinia.use(piniaPluginPersistedstate);
39

40
// In a store - basic persistence
41
import { defineStore } from 'pinia';
42
import { ref } from 'vue';
43

44
export const useStore = defineStore('store', {
45
  state: () => ({
46
    someState: 'hello pinia',
47
    count: 0,
48
  }),
49
  persist: true, // Enable persistence with defaults
50
});
51

52
// In a store - configured persistence
53
export const useAdvancedStore = defineStore('advanced', () => {
54
  const someState = ref('hello pinia');
55
  const secretData = ref('sensitive');
56
  
57
  return { someState, secretData };
58
}, {
59
  persist: {
60
    storage: sessionStorage,
61
    pick: ['someState'], // Only persist selected fields
62
  },
63
});
64
```
65

66
## Architecture
67

68
Pinia Plugin Persistedstate is built around several key components:
69

70
- **Plugin System**: Integrates with Pinia's plugin architecture to automatically handle store persistence
71
- **Storage Abstraction**: Supports multiple storage backends (localStorage, sessionStorage, custom storage)
72
- **Serialization Layer**: Configurable serialization/deserialization with JSON and destr by default
73
- **Selective Persistence**: Pick/omit specific state properties using dot-notation paths
74
- **SSR Support**: Nuxt module providing server-side rendering compatibility with cookie-based storage
75
- **Lifecycle Hooks**: beforeHydrate and afterHydrate hooks for custom persistence logic
76

77
## Capabilities
78

79
### Plugin Creation and Configuration
80

81
Core plugin creation with global configuration options for default behavior across all stores.
82

83
```typescript { .api }
84
function createPersistedState(options?: PluginOptions): (context: PiniaPluginContext) => void;
85

86
interface PluginOptions {
87
  /** Global storage backend */
88
  storage?: StorageLike;
89
  /** Enable debug logging */
90
  debug?: boolean;
91
  /** Global serializer */
92
  serializer?: Serializer;
93
  /** Global key generator */
94
  key?: (storeKey: string) => string;
95
  /** Auto-persist all stores */
96
  auto?: boolean;
97
}
98
```
99

100
[Plugin Configuration](./plugin-configuration.md)
101

102
### Store Persistence Options
103

104
Configuration options for individual store persistence behavior, including storage selection, state filtering, and lifecycle hooks.
105

106
```typescript { .api }
107
interface PersistenceOptions<State = any> {
108
  /** Storage key (defaults to store.$id) */
109
  key?: string;
110
  /** Enable debug logging */
111
  debug?: boolean;
112
  /** Storage backend */
113
  storage?: StorageLike;
114
  /** Serializer for state */
115
  serializer?: Serializer;
116
  /** Hook before hydration */
117
  beforeHydrate?: (context: PiniaPluginContext) => void;
118
  /** Hook after hydration */
119
  afterHydrate?: (context: PiniaPluginContext) => void;
120
  /** Paths to include in persistence */
121
  pick?: Path<State>[] | string[];
122
  /** Paths to exclude from persistence */
123
  omit?: Path<State>[] | string[];
124
}
125

126
type Persist<State = any> = boolean | PersistenceOptions<State> | PersistenceOptions<State>[];
127
```
128

129
[Store Persistence](./store-persistence.md)
130

131
### Nuxt Integration
132

133
SSR-friendly Nuxt module providing cookie-based storage and runtime configuration for seamless server-side rendering support.
134

135
```typescript { .api }
136
interface ModuleOptions {
137
  /** Enable debug logging */
138
  debug?: boolean;
139
  /** Default storage preset */
140
  storage?: 'cookies' | 'localStorage' | 'sessionStorage';
141
  /** Global key template */
142
  key?: `${string}%id${string}`;
143
  /** Cookie configuration */
144
  cookieOptions?: Omit<CookiesStorageOptions, 'encode' | 'decode'>;
145
  /** Auto-persist all stores */
146
  auto?: boolean;
147
}
148
```
149

150
[Nuxt Integration](./nuxt-integration.md)
151

152
## Types
153

154
```typescript { .api }
155
interface StorageLike {
156
  getItem: (key: string) => string | null;
157
  setItem: (key: string, value: string) => void;
158
}
159

160
interface Serializer {
161
  serialize: (data: any) => string;
162
  deserialize: (data: string) => any;
163
}
164

165
/**
166
 * Dot-notation path type for deep object property access
167
 * Examples: 'user.name', 'settings.theme', 'data.items.0.title'
168
 */
169
type Path<T> = string;
170
```