0
# Plugin Configuration
1

2
Core plugin creation and global configuration options for default behavior across all stores in a Pinia application.
3

4
## Capabilities
5

6
### Create Persisted State Plugin
7

8
Creates a Pinia persistence plugin with configurable global options.
9

10
```typescript { .api }
11
/**
12
 * Create a Pinia persistence plugin
13
 * @param options - Global plugin configuration options
14
 * @returns Pinia plugin function
15
 */
16
function createPersistedState(options?: PluginOptions): (context: PiniaPluginContext) => void;
17

18
interface PluginOptions {
19
  /** Global storage backend for all stores */
20
  storage?: StorageLike;
21
  /** Enable debug logging globally */
22
  debug?: boolean;
23
  /** Global serializer for all stores */
24
  serializer?: Serializer;
25
  /** Global key generator function */
26
  key?: (storeKey: string) => string;
27
  /** Automatically persist all stores with global defaults */
28
  auto?: boolean;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { createPinia } from 'pinia';
36
import { createPersistedState } from 'pinia-plugin-persistedstate';
37

38
// Default plugin (equivalent to imported default)
39
const pinia = createPinia();
40
pinia.use(createPersistedState());
41

42
// Plugin with global options
43
pinia.use(createPersistedState({
44
  storage: sessionStorage,
45
  debug: true,
46
  key: (storeKey) => `myapp:${storeKey}`,
47
  auto: true, // All stores persist by default
48
}));
49

50
// Custom serializer example
51
pinia.use(createPersistedState({
52
  serializer: {
53
    serialize: (data) => btoa(JSON.stringify(data)), // Base64 encoded
54
    deserialize: (data) => JSON.parse(atob(data)),
55
  },
56
}));
57
```
58

59
### Default Plugin Instance
60

61
Pre-configured plugin instance with default options, equivalent to `createPersistedState()`.
62

63
```typescript { .api }
64
/**
65
 * Default Pinia persistence plugin instance
66
 * Equivalent to createPersistedState() with no options
67
 */
68
declare const piniaPluginPersistedstate: (context: PiniaPluginContext) => void;
69
```
70

71
**Usage Example:**
72

73
```typescript
74
import { createPinia } from 'pinia';
75
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
76

77
const pinia = createPinia();
78
pinia.use(piniaPluginPersistedstate);
79
```
80

81
## Configuration Options
82

83
### Storage Option
84

85
Global storage backend that will be used by all stores unless overridden at the store level.
86

87
```typescript { .api }
88
interface PluginOptions {
89
  storage?: StorageLike;
90
}
91

92
interface StorageLike {
93
  getItem: (key: string) => string | null;
94
  setItem: (key: string, value: string) => void;
95
}
96
```
97

98
**Examples:**
99

100
```typescript
101
// Use sessionStorage globally
102
createPersistedState({
103
  storage: sessionStorage,
104
});
105

106
// Custom storage implementation
107
createPersistedState({
108
  storage: {
109
    getItem: (key) => localStorage.getItem(`custom:${key}`),
110
    setItem: (key, value) => localStorage.setItem(`custom:${key}`, value),
111
  },
112
});
113
```
114

115
### Debug Option
116

117
Enables console error logging for persistence operations across all stores.
118

119
```typescript { .api }
120
interface PluginOptions {
121
  debug?: boolean;
122
}
123
```
124

125
### Serializer Option
126

127
Global serializer for converting state to/from storage strings.
128

129
```typescript { .api }
130
interface PluginOptions {
131
  serializer?: Serializer;
132
}
133

134
interface Serializer {
135
  serialize: (data: any) => string;
136
  deserialize: (data: string) => any;
137
}
138
```
139

140
**Default serializer behavior:**
141
- `serialize`: `JSON.stringify`
142
- `deserialize`: `destr` (safe JSON parsing)
143

144
### Key Generator Option
145

146
Global function to transform store keys before storage.
147

148
```typescript { .api }
149
interface PluginOptions {
150
  key?: (storeKey: string) => string;
151
}
152
```
153

154
**Usage Example:**
155

156
```typescript
157
createPersistedState({
158
  key: (storeKey) => `v2:${storeKey}:state`, // Prefix with version
159
});
160
```
161

162
### Auto Persistence Option
163

164
When enabled, all stores will automatically persist unless explicitly disabled with `persist: false`.
165

166
```typescript { .api }
167
interface PluginOptions {
168
  auto?: boolean;
169
}
170
```
171

172
**Usage Example:**
173

174
```typescript
175
// All stores persist automatically
176
createPersistedState({ auto: true });
177

178
// Individual store opts out
179
export const useTemporaryStore = defineStore('temp', {
180
  state: () => ({ data: [] }),
181
  persist: false, // Explicitly disable
182
});
183
```