Pinia Plugin Persistedstate

https://prazdevs.github.io/pinia-plugin-persistedstate
Admin
Pinia Plugin Persistedstate is a configurable persistence plugin for Pinia stores that provides a...
Tokens:4,918
Snippets:62
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Pinia Plugin Persistedstate

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide

Install the package using your preferred package manager.

```sh
pnpm add pinia-plugin-persistedstate
```

```sh
npm i pinia-plugin-persistedstate
```

```sh
yarn add pinia-plugin-persistedstate
```

--------------------------------

### Configure persistence in Pinia stores

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Use the persist property within the store definition to customize persistence settings. This applies to both setup and option syntax.

```ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useStore = defineStore('main', () => {
  const someState = ref('hello pinia')
  return { someState }
}, {
  persist: {
    // CONFIG OPTIONS HERE
  }
})
```

```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    // CONFIG OPTIONS HERE
  },
})
```

--------------------------------

### Reference loss example

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/limitations.html

Demonstrates how object references are lost after the serialization and deserialization process.

```typescript
const a = {
  1: 'one',
  2: 'two',
  // ...
}
const b = a
```

```typescript
a === b // -> true
```

```typescript
a === b // -> false
```

--------------------------------

### createPersistedState(options)

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Initializes the plugin with global configuration options that apply to all stores by default.

```APIDOC
## createPersistedState(options)

### Description
Initializes the plugin with global options. These options become the new default for all stores within the app.

### Parameters
- **options** (Object) - Required
  - **storage** (Storage) - Optional - The storage engine to use (e.g., localStorage, sessionStorage).
  - **serializer** (Object) - Optional - Custom serializer for state data.
  - **debug** (boolean) - Optional - Enable debug logging.
  - **key** (Function) - Optional - A function that receives the store ID and returns a string to be used as the storage key.

### Example
```ts
import { createPinia } from 'pinia'
import { createPersistedState } from 'pinia-plugin-persistedstate'

const pinia = createPinia()

pinia.use(createPersistedState({
  storage: sessionStorage,
  key: (id) => `__persisted__${id}`
}))
```
```

--------------------------------

### Initialize Plugin with Global Options

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Use createPersistedState to set default persistence options for all stores in the application.

```typescript
import { 
createPinia
 } from 'pinia'
import { 
createPersistedState
 } from 'pinia-plugin-persistedstate'

const 
pinia
 = 
createPinia
()


pinia
.
use
(
createPersistedState
({
  
storage
: 
sessionStorage
,
}))
```

--------------------------------

### Register Plugin with Pinia

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide

Add the plugin to your Pinia instance during initialization.

```ts
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
```

--------------------------------

### Persist store state using VueUse

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/why.html

Demonstrates manual persistence of a Pinia store state using the VueUse useLocalStorage utility.

```typescript
import { useLocalStorage } from '@vueuse/core'
import { defineStore } from 'pinia'

defineStore('store', () => {
  const someState = useLocalStorage('stored-state', 'initialValue')

  return { someState }
})
```

--------------------------------

### store.$hydrate(options)

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Manually triggers the hydration of the store state from the configured storage.

```APIDOC
## store.$hydrate(options)

### Description
Manually triggers hydration from storage. By default, this triggers `beforeHydrate` and `afterHydrate` hooks.

### Parameters
- **options** (Object) - Optional
  - **runHooks** (boolean) - Optional - Set to false to skip triggering hydration hooks.

### Example
```ts
const store = useStore()
store.$hydrate({ runHooks: false })
```
```

--------------------------------

### Enable Persistence in Stores

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide

Enable state persistence by setting the persist option to true in your store definition.

```ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useStore = defineStore(
  'main',
  () => {
    const someState = ref('hello pinia')
    return { someState }
  },
  {
    persist: true,
  },
)
```

```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    }
  },
  persist: true,
})
```

--------------------------------

### Configure storage types

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/frameworks/nuxt.html

Specify the storage engine using the auto-imported piniaPluginPersistedstate variable.

```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    }
  },
  persist: {
    storage: piniaPluginPersistedstate.cookies(),
  },
})
```

```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    }
  },
  persist: {
    storage: piniaPluginPersistedstate.localStorage(),
  },
})
```

```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    }
  },
  persist: {
    storage: piniaPluginPersistedstate.sessionStorage(),
  },
})
```

--------------------------------

### Set global module options

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/frameworks/nuxt.html

Configure global persistence settings in nuxt.config.ts under the piniaPluginPersistedstate key.

```ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    'pinia-plugin-persistedstate/nuxt'
  ],
  piniaPluginPersistedstate: {
    storage: 'cookies',
    cookieOptions: {
      sameSite: 'lax',
    },
    debug: true,
  },
})
```

--------------------------------

### Define Multiple Persistence Configurations

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Apply multiple persistence strategies to a single store by providing an array of configurations.

```typescript
import { 
defineStore
 } from 'pinia'


defineStore
('store', {
  
state
: () => ({
    
toLocal
: '',
    
toSession
: '',
    
toNowhere
: '',
  }),
  
persist
: [
    {
      
pick
: ['toLocal'],
      
storage
: 
localStorage
,
    },
    {
      
pick
: ['toSession'],
      
storage
: 
sessionStorage
,
    },
  ],
})
```

```typescript
import { 
defineStore
 } from 'pinia'


defineStore
('store', {
  
state
: () => ({
    
someData
: 'Hello Pinia'
  }),
  
persist
: [
    {
      
storage
: 
localStorage
,
    },
    {
      
storage
: 
sessionStorage
,
    },
  ],
})
```

--------------------------------

### store.$persist()

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Manually triggers the persistence of the current store state to the configured storage.

```APIDOC
## store.$persist()

### Description
Forces the store state to be persisted in the configured storages immediately.

### Example
```ts
const store = useStore()
store.$persist()
```
```

--------------------------------

### Implement beforeHydrate Hook

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Execute logic before the store state is hydrated with persisted data using the PiniaPluginContext.

```ts
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someState
: 'hello pinia',
  }),
  
persist
: {
    
beforeHydrate
: (
ctx
) => {
      
console
.
log
(`about to hydrate '${
ctx
.
store
.
$id
}'`)
    }
  },
})
```

--------------------------------

### Configure Nuxt module

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/frameworks/nuxt.html

Add the plugin to the modules array in your nuxt.config.ts file.

```ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    'pinia-plugin-persistedstate/nuxt',
  ],
})
```

--------------------------------

### Pick Specific State Paths

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Define an array of dot-notation paths to persist only specific parts of the store state.

```ts
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
save
: {
      
me
: 'saved',
      
notMe
: 'not-saved',
    },
    
saveMeToo
: 'saved',
  }),
  
persist
: {
    
pick
: ['save.me', 'saveMeToo'],
  },
})
```

--------------------------------

### Configure Custom Serializer

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Use a custom serializer to handle data transformation, such as compression with zipson.

```ts
import { defineStore } from 'pinia'
import { parse, stringify } from 'zipson'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    serializer: {
      deserialize: parse,
      serialize: stringify
    }
  },
})
```

--------------------------------

### Configure Global Key Factory

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Define a custom key generation function globally to prefix or transform store keys.

```typescript
import { 
createPinia
 } from 'pinia'
import { 
createPersistedState
 } from 'pinia-plugin-persistedstate'

const 
pinia
 = 
createPinia
()


pinia
.
use
(
createPersistedState
({
  
key
: 
id
 => `__persisted__${
id
}`,
}))
```

```typescript
import { 
defineStore
 } from 'pinia'


defineStore
('store', {
  
state
: () => ({ 
saved
: '' }),
  
persist
: true,
})
```

--------------------------------

### Configure global persistence key in Nuxt

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/frameworks/nuxt.html

Define a global key template in nuxt.config.ts using the %id token to prefix or postfix store keys.

```typescript
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    'pinia-plugin-persistedstate/nuxt'
  ],
  piniaPluginPersistedstate: {
    key: 'prefix_%id_postfix',
  },
})
```

--------------------------------

### Specify a custom storage engine

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Change the storage destination by assigning a StorageLike object to the storage property. The engine must implement synchronous getItem and setItem methods.

```ts
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someState
: 'hello pinia',
  }),
  
persist
: {
    
storage
: 
sessionStorage
,
  },
})
```

--------------------------------

### Implement afterHydrate hook in Pinia store

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Use this hook to execute logic immediately after a store has been rehydrated from persistence. Access the full PiniaPluginContext within the callback.

```typescript
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someState
: 'hello pinia',
  }),
  
persist
: {
    
afterHydrate
: (
ctx
) => {
      
console
.
log
(`just hydrated '${
ctx
.
store
.
$id
}'`)
    }
  },
})
```

--------------------------------

### debug

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

A boolean flag to enable logging of errors that occur during persistence or hydration.

```APIDOC
## debug

### Description
When set to true, any error that may occur while persisting/hydrating stores will be logged with `console.error`.

### Type
`boolean`

### Default
`false`

### Warning
No environment check is done: if this is enabled, errors will also be logged in production.
```

--------------------------------

### Manually Trigger Persistence

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Use the $persist method to force the current store state to be saved to configured storages.

```typescript
import { 
defineStore
 } from 'pinia'

const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someData
: 'Hello Pinia'
  })
})
```

```typescript
const store = useStore()

store.$persist()
```

--------------------------------

### Manually Trigger Hydration

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/advanced.html

Use the $hydrate method to manually reload state from storage, optionally skipping hooks.

```typescript
import { 
defineStore
 } from 'pinia'

const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someData
: 'Hello Pinia'
  })
})
```

```typescript
const store = useStore()

store.$hydrate({ runHooks: false })
```

--------------------------------

### Omit Specific State Paths

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Define an array of dot-notation paths to exclude specific parts of the store state from persistence.

```ts
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
ignore
: {
      
me
: 'not-saved',
      
notMe
: 'saved',
    },
    
ignoreMeToo
: 'not-saved',
  }),
  
persist
: {
    
omit
: ['ignore.me', 'ignoreMeToo'],
  },
})
```

--------------------------------

### Define a custom storage key

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

Override the default store ID key by providing a custom string to the key property.

```ts
import { 
defineStore
 } from 'pinia'

export const 
useStore
 = 
defineStore
('store', {
  
state
: () => ({
    
someState
: 'hello pinia',
  }),
  
persist
: {
    
key
: 'my-custom-key',
  },
})
```

--------------------------------

### afterHydrate

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/guide/config.html

A hook function that executes after the state has been rehydrated. It provides access to the PiniaPluginContext.

```APIDOC
## afterHydrate

### Description
Hook function run after rehydrating a persisted state. The hook gives access to the whole `PiniaPluginContext` and can be used to enforce specific actions after hydration.

### Type
`(context: PiniaPluginContext) => void`

### Default
`undefined`

### Example
```ts
import { defineStore } from 'pinia'

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
  }),
  persist: {
    afterHydrate: (ctx) => {
      console.log(`just hydrated '${ctx.store.$id}'`)
    }
  },
})
```
```

--------------------------------

### Use maxAge for cookies in Cloudflare Workers

Source: https://prazdevs.github.io/pinia-plugin-persistedstate/frameworks/nuxt.html

Avoid using Javascript Date objects for cookie expiration in Cloudflare Workers by using maxAge instead.

```typescript
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useStore = defineStore(
  'main',
  () => {
    const someState = ref('hello pinia')
    return { someState }
  },
  {
    persist: piniaPluginPersistedstate.cookies({
      // DO NOT USE - the date in cloudflare worker will return 1970-01-01
      expires: new Date(new Date().setFullYear(new Date().getFullYear() + 1)),
      // USE THIS INSTEAD
      maxAge: 365 * 24 * 60 * 60,
    }),
  },
)
```
Tokens:
Raw