0
# Nuxt Integration
1

2
SSR-friendly Nuxt module providing cookie-based storage and runtime configuration for seamless server-side rendering support. The module automatically configures Pinia persistence with Nuxt-specific optimizations.
3

4
## Capabilities
5

6
### Nuxt Module Configuration
7

8
Configure the Nuxt module in your `nuxt.config.ts` file with global defaults and SSR-friendly settings.
9

10
```typescript { .api }
11
/**
12
 * Nuxt module options for pinia-plugin-persistedstate
13
 */
14
interface ModuleOptions {
15
  /** Enable debug logging */
16
  debug?: boolean;
17
  /** Default storage preset for all stores */
18
  storage?: 'cookies' | 'localStorage' | 'sessionStorage';
19
  /** Global key template with %id placeholder */
20
  key?: `${string}%id${string}`;
21
  /** Cookie configuration options */
22
  cookieOptions?: Omit<CookiesStorageOptions, 'encode' | 'decode'>;
23
  /** Automatically persist all stores */
24
  auto?: boolean;
25
}
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
// nuxt.config.ts
32
export default defineNuxtConfig({
33
  modules: [
34
    '@pinia/nuxt', // Required dependency
35
    'pinia-plugin-persistedstate/nuxt',
36
  ],
37
  piniaPluginPersistedstate: {
38
    storage: 'cookies',
39
    debug: true,
40
    key: 'myapp-%id',
41
    auto: true,
42
  },
43
});
44

45
// Minimal configuration
46
export default defineNuxtConfig({
47
  modules: [
48
    '@pinia/nuxt',
49
    'pinia-plugin-persistedstate/nuxt',
50
  ],
51
});
52
```
53

54
### Nuxt Storage Implementations
55

56
Server-safe storage implementations that work seamlessly between server and client rendering.
57

58
```typescript { .api }
59
/**
60
 * Cookie storage options for Nuxt
61
 */
62
interface CookiesStorageOptions {
63
  /** Cookie domain */
64
  domain?: string;
65
  /** Cookie expiration */
66
  expires?: Date;
67
  /** HTTP only flag */
68
  httpOnly?: boolean;
69
  /** Cookie max age in seconds */
70
  maxAge?: number;
71
  /** Cookie path */
72
  path?: string;
73
  /** Require HTTPS */
74
  secure?: boolean;
75
  /** SameSite policy */
76
  sameSite?: 'strict' | 'lax' | 'none';
77
  /** Custom encode function */
78
  encode?: (value: string) => string;
79
  /** Custom decode function */
80
  decode?: (value: string) => string;
81
}
82

83
/**
84
 * Storage implementations for Nuxt runtime
85
 */
86
interface StorageImplementations {
87
  /** Cookie-based storage (SSR-friendly) */
88
  cookies: (options?: CookiesStorageOptions) => StorageLike;
89
  /** localStorage wrapper (client-side only) */
90
  localStorage: () => StorageLike;
91
  /** sessionStorage wrapper (client-side only) */
92
  sessionStorage: () => StorageLike;
93
}
94

95
declare const storages: StorageImplementations;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
// In a Nuxt store with custom storage
102
export const useStore = defineStore('store', {
103
  state: () => ({ data: 'hello' }),
104
  persist: {
105
    // Use cookies with custom options
106
    storage: piniaPluginPersistedstate.cookies({
107
      maxAge: 60 * 60 * 24 * 7, // 7 days
108
      secure: true,
109
      sameSite: 'strict',
110
    }),
111
  },
112
});
113

114
// Use client-side storage in Nuxt
115
export const useClientStore = defineStore('client', {
116
  state: () => ({ clientData: [] }),
117
  persist: {
118
    storage: piniaPluginPersistedstate.localStorage(),
119
  },
120
});
121
```
122

123
## Module Configuration Options
124

125
### Storage Preset
126

127
Default storage type for all stores in the Nuxt application.
128

129
```typescript { .api }
130
interface ModuleOptions {
131
  storage?: 'cookies' | 'localStorage' | 'sessionStorage';
132
}
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
// Use cookies by default (SSR-safe)
139
piniaPluginPersistedstate: {
140
  storage: 'cookies',
141
}
142

143
// Use localStorage by default (client-only)
144
piniaPluginPersistedstate: {
145
  storage: 'localStorage',
146
}
147
```
148

149
### Key Template
150

151
Global key template with placeholder replacement for consistent naming.
152

153
```typescript { .api }
154
interface ModuleOptions {
155
  key?: `${string}%id${string}`;
156
}
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
piniaPluginPersistedstate: {
163
  key: 'myapp-%id-state', // 'user' store becomes 'myapp-user-state'
164
}
165

166
piniaPluginPersistedstate: {
167
  key: 'v2:%id', // 'cart' store becomes 'v2:cart'
168
}
169
```
170

171
### Cookie Options
172

173
Global cookie configuration for stores using cookie storage.
174

175
```typescript { .api }
176
interface ModuleOptions {
177
  cookieOptions?: Omit<CookiesStorageOptions, 'encode' | 'decode'>;
178
}
179
```
180

181
**Usage Example:**
182

183
```typescript
184
piniaPluginPersistedstate: {
185
  storage: 'cookies',
186
  cookieOptions: {
187
    maxAge: 60 * 60 * 24 * 30, // 30 days
188
    secure: true,
189
    sameSite: 'strict',
190
    path: '/',
191
  },
192
}
193
```
194

195
### Auto Persistence
196

197
Automatically enable persistence for all stores with global defaults.
198

199
```typescript { .api }
200
interface ModuleOptions {
201
  auto?: boolean;
202
}
203
```
204

205
**Usage Example:**
206

207
```typescript
208
piniaPluginPersistedstate: {
209
  auto: true, // All stores persist automatically
210
  storage: 'cookies', // Default storage for auto-persisted stores
211
}
212
```
213

214
## SSR Considerations
215

216
### Cookie Storage Benefits
217

218
- **SSR Compatible**: Works on both server and client
219
- **Hydration Safe**: Prevents hydration mismatches
220
- **Secure**: Supports httpOnly, secure, and sameSite options
221

222
### Client-Side Storage Limitations
223

224
- **localStorage/sessionStorage**: Only work client-side
225
- **Hydration**: Can cause server/client mismatches
226
- **SEO**: Not available during server rendering
227

228
**Best Practices:**
229

230
```typescript
231
// SSR-friendly approach
232
export const useUserStore = defineStore('user', {
233
  state: () => ({ preferences: { theme: 'light' } }),
234
  persist: {
235
    storage: piniaPluginPersistedstate.cookies({
236
      maxAge: 60 * 60 * 24 * 365, // 1 year
237
    }),
238
  },
239
});
240

241
// Client-only approach (use with care)
242
export const useLocalStore = defineStore('local', {
243
  state: () => ({ tempData: [] }),
244
  persist: {
245
    storage: piniaPluginPersistedstate.localStorage(),
246
  },
247
});
248
```
249

250
## Runtime Configuration
251

252
The module automatically provides runtime configuration accessible in your Nuxt application:
253

254
```typescript { .api }
255
interface PublicRuntimeConfig {
256
  piniaPluginPersistedstate: ModuleOptions;
257
}
258
```
259

260
**Usage Example:**
261

262
```typescript
263
// Access runtime config in components or composables
264
const config = useRuntimeConfig();
265
console.log(config.public.piniaPluginPersistedstate);
266
```