CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pinia-plugin-persistedstate

Configurable persistence and rehydration of Pinia stores with SSR-friendly Nuxt integration.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

Pinia Plugin Persistedstate

Pinia Plugin Persistedstate provides configurable persistence and rehydration of Pinia stores in Vue.js applications. It offers a friendly API inspired by vuex-persistedstate with highly customizable options including storage backends, serialization methods, and selective state picking/omitting. The plugin features out-of-the-box SSR-friendly support for Nuxt applications and maintains a very small bundle size (<2kB minzipped).

Package Information

  • Package Name: pinia-plugin-persistedstate
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install pinia-plugin-persistedstate

Core Imports

import piniaPluginPersistedstate, { 
  createPersistedState,
  type PluginOptions,
  type PersistenceOptions,
  type Serializer,
  type StorageLike
} from "pinia-plugin-persistedstate";

For CommonJS:

const piniaPluginPersistedstate = require("pinia-plugin-persistedstate");
const { createPersistedState } = require("pinia-plugin-persistedstate");

Basic Usage

import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

// Add plugin to Pinia
const pinia = createPinia();
pinia.use(piniaPluginPersistedstate);

// In a store - basic persistence
import { defineStore } from 'pinia';
import { ref } from 'vue';

export const useStore = defineStore('store', {
  state: () => ({
    someState: 'hello pinia',
    count: 0,
  }),
  persist: true, // Enable persistence with defaults
});

// In a store - configured persistence
export const useAdvancedStore = defineStore('advanced', () => {
  const someState = ref('hello pinia');
  const secretData = ref('sensitive');
  
  return { someState, secretData };
}, {
  persist: {
    storage: sessionStorage,
    pick: ['someState'], // Only persist selected fields
  },
});

Architecture

Pinia Plugin Persistedstate is built around several key components:

  • Plugin System: Integrates with Pinia's plugin architecture to automatically handle store persistence
  • Storage Abstraction: Supports multiple storage backends (localStorage, sessionStorage, custom storage)
  • Serialization Layer: Configurable serialization/deserialization with JSON and destr by default
  • Selective Persistence: Pick/omit specific state properties using dot-notation paths
  • SSR Support: Nuxt module providing server-side rendering compatibility with cookie-based storage
  • Lifecycle Hooks: beforeHydrate and afterHydrate hooks for custom persistence logic

Capabilities

Plugin Creation and Configuration

Core plugin creation with global configuration options for default behavior across all stores.

function createPersistedState(options?: PluginOptions): (context: PiniaPluginContext) => void;

interface PluginOptions {
  /** Global storage backend */
  storage?: StorageLike;
  /** Enable debug logging */
  debug?: boolean;
  /** Global serializer */
  serializer?: Serializer;
  /** Global key generator */
  key?: (storeKey: string) => string;
  /** Auto-persist all stores */
  auto?: boolean;
}

Plugin Configuration

Store Persistence Options

Configuration options for individual store persistence behavior, including storage selection, state filtering, and lifecycle hooks.

interface PersistenceOptions<State = any> {
  /** Storage key (defaults to store.$id) */
  key?: string;
  /** Enable debug logging */
  debug?: boolean;
  /** Storage backend */
  storage?: StorageLike;
  /** Serializer for state */
  serializer?: Serializer;
  /** Hook before hydration */
  beforeHydrate?: (context: PiniaPluginContext) => void;
  /** Hook after hydration */
  afterHydrate?: (context: PiniaPluginContext) => void;
  /** Paths to include in persistence */
  pick?: Path<State>[] | string[];
  /** Paths to exclude from persistence */
  omit?: Path<State>[] | string[];
}

type Persist<State = any> = boolean | PersistenceOptions<State> | PersistenceOptions<State>[];

Store Persistence

Nuxt Integration

SSR-friendly Nuxt module providing cookie-based storage and runtime configuration for seamless server-side rendering support.

interface ModuleOptions {
  /** Enable debug logging */
  debug?: boolean;
  /** Default storage preset */
  storage?: 'cookies' | 'localStorage' | 'sessionStorage';
  /** Global key template */
  key?: `${string}%id${string}`;
  /** Cookie configuration */
  cookieOptions?: Omit<CookiesStorageOptions, 'encode' | 'decode'>;
  /** Auto-persist all stores */
  auto?: boolean;
}

Nuxt Integration

Types

interface StorageLike {
  getItem: (key: string) => string | null;
  setItem: (key: string, value: string) => void;
}

interface Serializer {
  serialize: (data: any) => string;
  deserialize: (data: string) => any;
}

/**
 * Dot-notation path type for deep object property access
 * Examples: 'user.name', 'settings.theme', 'data.items.0.title'
 */
type Path<T> = string;

Install with Tessl CLI

npx tessl i tessl/npm-pinia-plugin-persistedstate

docs

index.md

nuxt-integration.md

plugin-configuration.md

store-persistence.md

tile.json