DOCSEARCHbyAlgolia
Submit Docs

Pinia Plugin Persistedstate

website·Indexed 29 days ago

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

A plugin for Pinia (compatible with pinia >= 2.0.0) that allows persisting stores with a friendly API inspired by vuex-persistedstate. It includes a Nuxt module for SSR-friendly persistence and supports custom synchronous storage, global persistence options via createPersistedState, and configurable keys.

Tokens
6.4K
Snippets
43
Records
53
Agent score
73%

What's inside Pinia Plugin Persistedstate

  1. Understand the purpose of pinia-plugin-persistedstate

    The pinia-plugin-persistedstate plugin provides a consistent API for persisting Pinia stores. While simple persistence can be achieved manually (e.g., using VueUse), this plugin is designed for developers who need a standardized approach across projects, ranging from simple default persistence of an entire store to fine-grained configurations involving multiple storage engines and custom serializers, all managed via a single persist option on the store.

  2. Persist Pinia stores using pinia-plugin-persistedstate

    The pinia-plugin-persistedstate plugin provides a consistent API to persist Pinia store data to storage (such as localStorage). It is designed for projects that need a standardized way to handle persistence, ranging from simple default setups (saving the entire store) to advanced configurations involving multiple storages and custom serializers, all managed via the persist option within the store definition.

  3. Enable persistence for a Pinia store

    To persist a store using the default settings, add the persist: true option to the store definition. This works with both Setup and Option syntax.
    import { defineStore } from 'pinia'
import { ref } from 'vue'

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

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

  4. Handle synchronous storage requirements in pinia-plugin-persistedstate

    When providing a custom storage implementation, the storage methods must be synchronous. This is because Pinia's state subscription ($subscribe) operates synchronously. If asynchronous behavior is required (e.g., using an asynchronous storage engine), use Pinia's $onAction subscription instead.

  5. Persist state in Pinia Setup Stores

    When using the Setup Store syntax (composition API), only ref() variables that are explicitly returned from the setup function are persisted. computed() properties cannot be persisted regardless of whether they are returned, as Pinia treats ref()s as state and computed()s as getters. All state properties must be returned in the setup store for Pinia to recognize them as state.

  6. Use pinia-plugin-persistedstate with non-Nuxt Vue frameworks

    While there are no plans for official support for Vue frameworks other than Nuxt, pinia-plugin-persistedstate can be used in most frameworks as a standard Pinia plugin. Users should be aware of potential Server-Side Rendering (SSR) warnings when integrating with these frameworks.

  7. Install and initialize pinia-plugin-persistedstate

    To enable persistence for Pinia stores, install the pinia-plugin-persistedstate package and register it as a plugin in your Pinia instance. This plugin is compatible with pinia >= 2.0.0.
    # Using pnpm
pnpm add pinia-plugin-persistedstate

# Using npm
npm i pinia-plugin-persistedstate

# Using yarn
yarn add pinia-plugin-persistedstate
    import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

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

  8. Install pinia-plugin-persistedstate in Nuxt

    Install the pinia-plugin-persistedstate package and add the Nuxt module to your configuration to enable SSR-friendly persistence.
    # Using pnpm
pnpm add pinia-plugin-persistedstate
# Using npm
npm i pinia-plugin-persistedstate
# Using yarn
yarn add pinia-plugin-persistedstate
    // nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    'pinia-plugin-persistedstate/nuxt',
  ],
})

  9. Install and initialize pinia-plugin-persistedstate

    To enable state persistence in Pinia, install the pinia-plugin-persistedstate package and register it with your Pinia instance. This plugin is compatible with pinia >= 2.0.0.
    # Using pnpm
pnpm add pinia-plugin-persistedstate

# Using npm
npm i pinia-plugin-persistedstate

# Using yarn
yarn add pinia-plugin-persistedstate
    import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

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

  10. Install pinia-plugin-persistedstate in Nuxt

    To enable SSR-friendly state persistence in Nuxt, install the pinia-plugin-persistedstate package and add the corresponding module to your Nuxt configuration.
    # Using pnpm
pnpm add pinia-plugin-persistedstate
# Using npm
npm i pinia-plugin-persistedstate
# Using yarn
yarn add pinia-plugin-persistedstate
    // nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',
    'pinia-plugin-persistedstate/nuxt',
  ],
})

  11. Use pinia-plugin-persistedstate with non-Nuxt Vue frameworks

    While official support is primarily focused on Nuxt, pinia-plugin-persistedstate can be used in most other Vue frameworks (such as Quasar, Ionic, or Vike) as it functions like any standard Pinia plugin. When implementing in these frameworks, be mindful of potential Server-Side Rendering (SSR) caveats.

  12. Configure storage for Pinia stores in Nuxt

    You can specify the storage mechanism using the auto-imported piniaPluginPersistedstate variable.

    • cookies(): SSR-friendly. Supports options inherited from Nuxt's useCookie (e.g., domain, expires, maxAge, path, sameSite, secure). Note: Cookie size is limited to 4098 bytes.
    • localStorage(): Client-side only.
    • sessionStorage(): Client-side only.
    import { defineStore } from 'pinia'

export const useStore = defineStore('main', {
  state: () => ({ someState: 'hello pinia' }),
  persist: {
    // Choose one of the following:
    storage: piniaPluginPersistedstate.cookies({
      sameSite: 'lax',
      maxAge: 365 * 24 * 60 * 60,
    }),
    // storage: piniaPluginPersistedstate.localStorage(),
    // storage: piniaPluginPersistedstate.sessionStorage(),
  },
})