Usage with Nuxt

The pinia-plugin-persistedstate package comes with a Nuxt module to offer an SSR-friendly experience out of the box.

Installation

1. Install the dependency with your favorite package manager:

pnpm

pnpm add pinia-plugin-persistedstate

npm

npm i pinia-plugin-persistedstate

yarn

yarn add pinia-plugin-persistedstate

1. Add the module to the Nuxt config:

nuxt.config.ts

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

Usage

When declaring your store, set the new persist option to true.

setup syntax

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

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

option syntax

import { defineStore } from 'pinia'

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

Defaults

The Nuxt module comes pre-configured with the following:

• cookies as storage.
• store.$id as default key for storage.
• JSON.stringify/destr as serializer/deserializer.
• The whole state is persisted to the storage.

Choosing a storage

You can configure what storage you want to use by using the storages available under the auto-imported piniaPluginPersistedstate variable.

WARNING

Using other storages than the ones exposed by persistedState may have unexpected behaviors.

cookies

import { defineStore } from 'pinia'

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

TIP

The persistedState.cookies method accept an object parameter to configure cookies with the following options (inherited from Nuxt’s useCookie):

• domain
• expires
• httpOnly
• maxAge
• partitioned
• path
• sameSite
• secure

WARNING

Be careful when saving stores with a lot of data as cookie size is limited to 4098 bytes. More on cookie storage in the MDN documentation.

localStorage

import { defineStore } from 'pinia'

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

> `localStorage` is client side only.

sessionStorage

import { defineStore } from 'pinia'

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

> `sessionStorage` is client side only.

Global options

The module accepts some options defined in nuxt.config.ts under the piniaPluginPersistedstate key:

• cookieOptions
• debug
• key
• storage

NOTE

The global storage option only accepts string values of pre-configured storages ('cookies', 'localStorage', 'sessionStorage'). This is due Nuxt’s way of passing module options to runtime.

nuxt.config.ts

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

Global key

You can provide a template string to prefix/postfix keys used globally. The provided key must include the token %id which will be replaced by the corresponding store’s id.

nuxt.config.ts

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

Any store with my-store as persistence key (user-provided or infered from store id) will be persisted under the prefix_my-store_postfix key.