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

Nuxt Integration

Name: tessl/npm-pinia-plugin-persistedstate
Author: tessl

SSR-friendly Nuxt module providing cookie-based storage and runtime configuration for seamless server-side rendering support. The module automatically configures Pinia persistence with Nuxt-specific optimizations.

Capabilities

Nuxt Module Configuration

Configure the Nuxt module in your nuxt.config.ts file with global defaults and SSR-friendly settings.

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

Usage Examples:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt', // Required dependency
    'pinia-plugin-persistedstate/nuxt',
  ],
  piniaPluginPersistedstate: {
    storage: 'cookies',
    debug: true,
    key: 'myapp-%id',
    auto: true,
  },
});

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

Nuxt Storage Implementations

Server-safe storage implementations that work seamlessly between server and client rendering.

/**
 * Cookie storage options for Nuxt
 */
interface CookiesStorageOptions {
  /** Cookie domain */
  domain?: string;
  /** Cookie expiration */
  expires?: Date;
  /** HTTP only flag */
  httpOnly?: boolean;
  /** Cookie max age in seconds */
  maxAge?: number;
  /** Cookie path */
  path?: string;
  /** Require HTTPS */
  secure?: boolean;
  /** SameSite policy */
  sameSite?: 'strict' | 'lax' | 'none';
  /** Custom encode function */
  encode?: (value: string) => string;
  /** Custom decode function */
  decode?: (value: string) => string;
}

/**
 * Storage implementations for Nuxt runtime
 */
interface StorageImplementations {
  /** Cookie-based storage (SSR-friendly) */
  cookies: (options?: CookiesStorageOptions) => StorageLike;
  /** localStorage wrapper (client-side only) */
  localStorage: () => StorageLike;
  /** sessionStorage wrapper (client-side only) */
  sessionStorage: () => StorageLike;
}

declare const storages: StorageImplementations;

Usage Examples:

// In a Nuxt store with custom storage
export const useStore = defineStore('store', {
  state: () => ({ data: 'hello' }),
  persist: {
    // Use cookies with custom options
    storage: piniaPluginPersistedstate.cookies({
      maxAge: 60 * 60 * 24 * 7, // 7 days
      secure: true,
      sameSite: 'strict',
    }),
  },
});

// Use client-side storage in Nuxt
export const useClientStore = defineStore('client', {
  state: () => ({ clientData: [] }),
  persist: {
    storage: piniaPluginPersistedstate.localStorage(),
  },
});

Module Configuration Options

Storage Preset

Default storage type for all stores in the Nuxt application.

interface ModuleOptions {
  storage?: 'cookies' | 'localStorage' | 'sessionStorage';
}

Usage Examples:

// Use cookies by default (SSR-safe)
piniaPluginPersistedstate: {
  storage: 'cookies',
}

// Use localStorage by default (client-only)
piniaPluginPersistedstate: {
  storage: 'localStorage',
}

Key Template

Global key template with placeholder replacement for consistent naming.

interface ModuleOptions {
  key?: `${string}%id${string}`;
}

Usage Examples:

piniaPluginPersistedstate: {
  key: 'myapp-%id-state', // 'user' store becomes 'myapp-user-state'
}

piniaPluginPersistedstate: {
  key: 'v2:%id', // 'cart' store becomes 'v2:cart'
}

Cookie Options

Global cookie configuration for stores using cookie storage.

interface ModuleOptions {
  cookieOptions?: Omit<CookiesStorageOptions, 'encode' | 'decode'>;
}

Usage Example:

piniaPluginPersistedstate: {
  storage: 'cookies',
  cookieOptions: {
    maxAge: 60 * 60 * 24 * 30, // 30 days
    secure: true,
    sameSite: 'strict',
    path: '/',
  },
}

Auto Persistence

Automatically enable persistence for all stores with global defaults.

interface ModuleOptions {
  auto?: boolean;
}

Usage Example:

piniaPluginPersistedstate: {
  auto: true, // All stores persist automatically
  storage: 'cookies', // Default storage for auto-persisted stores
}

SSR Considerations

Cookie Storage Benefits

SSR Compatible: Works on both server and client
Hydration Safe: Prevents hydration mismatches
Secure: Supports httpOnly, secure, and sameSite options

Client-Side Storage Limitations

localStorage/sessionStorage: Only work client-side
Hydration: Can cause server/client mismatches
SEO: Not available during server rendering

Best Practices:

// SSR-friendly approach
export const useUserStore = defineStore('user', {
  state: () => ({ preferences: { theme: 'light' } }),
  persist: {
    storage: piniaPluginPersistedstate.cookies({
      maxAge: 60 * 60 * 24 * 365, // 1 year
    }),
  },
});

// Client-only approach (use with care)
export const useLocalStore = defineStore('local', {
  state: () => ({ tempData: [] }),
  persist: {
    storage: piniaPluginPersistedstate.localStorage(),
  },
});

Runtime Configuration

The module automatically provides runtime configuration accessible in your Nuxt application:

interface PublicRuntimeConfig {
  piniaPluginPersistedstate: ModuleOptions;
}

Usage Example:

// Access runtime config in components or composables
const config = useRuntimeConfig();
console.log(config.public.piniaPluginPersistedstate);

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

tessl/npm-pinia-plugin-persistedstate