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

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pinia-plugin-persistedstate@4.5.x
Publish Source
CLI
Badge
tessl/npm-pinia-plugin-persistedstate badge