zustand-persist-plus

Advanced persistence extensions for Zustand v5 — encryption, compression, migrations, and cloud sync.

Why zustand-persist-plus?

Building robust persistence in Zustand is hard. This plugin makes it effortless:

| Feature | Without zustand-persist-plus | With zustand-persist-plus | |---------|------------------------------|---------------------------| | Encryption | Manual crypto-js integration | One-line middleware | | Compression | Custom LZ-string logic | Auto compression middleware | | Migrations | Write your own migration engine | Built-in version control | | Cloud Sync | Complex Supabase/Firebase setup | Drop-in sync adapters | | TypeScript | Generic types, errors everywhere | Full strict typing |

Features

• 🔐 Encryption — AES-GCM and XSalsa20 encryption for secure data storage
• 📦 Compression — LZ-String compression to reduce storage size by 60-80%
• 🔄 Migration — Built-in schema migration with automatic version tracking
• ☁️ Cloud Sync — Firebase & Supabase real-time sync with conflict resolution
• 📄 TypeScript — Full strict typing with zero configuration
• ⚡ Zero Runtime Overhead — Tree-shakeable, minimal bundle size

Installation

npm install zustand-persist-plus zustand@^5.0.0
# or
pnpm add zustand-persist-plus zustand@^5.0.0
# or
yarn add zustand-persist-plus zustand@^5.0.0

Quick Start

import { create } from 'zustand'
import { persist, withEncryption, withCompression } from 'zustand-persist-plus'

const useStore = create(
  persist(
    withEncryption('your-secret-key')(
      withCompression()(
        (set) => ({
          count: 0,
          increment: () => set((state) => ({ count: state.count + 1 }))
        })
      )
    ),
    { name: 'my-store' }
  )
)

Usage

Encryption

Protect sensitive user data with military-grade encryption:

import { create } from 'zustand'
import { persist, withEncryption } from 'zustand-persist-plus'

interface AuthStore {
  token: string | null
  user: User | null
  setAuth: (token: string, user: User) => void
  logout: () => void
}

const useAuthStore = create<AuthStore>()(
  persist(
    withEncryption(process.env.NEXT_PUBLIC_ENCRYPTION_KEY!, {
      algorithm: 'AES-GCM',
      encode: true
    })(
      (set) => ({
        token: null,
        user: null,
        setAuth: (token, user) => set({ token, user }),
        logout: () => set({ token: null, user: null })
      })
    ),
    { name: 'auth-store' }
  )
)

Compression

Store large datasets efficiently:

import { create } from 'zustand'
import { persist, withCompression } from 'zustand-persist-plus'

interface DataStore {
  documents: Document[]
  setDocuments: (docs: Document[]) => void
}

const useDataStore = create<DataStore>()(
  persist(
    withCompression({ minSize: 1024 })(
      (set) => ({
        documents: [],
        setDocuments: (docs) => set({ documents: docs })
      })
    ),
    { name: 'data-store' }
  )
)

Migrations

Evolve your store schema without breaking user data:

import { create } from 'zustand'
import { persist, withMigrations } from 'zustand-persist-plus'

interface StoreV2 {
  user: { name: string; email: string }
  settings: { theme: 'light' | 'dark' }
}

const migrations = {
  // Migrate from v1 to v2
  2: (state: any) => ({
    ...state,
    _version: 2,
    settings: {
      ...state.settings,
      theme: state.settings.theme ?? 'light'
    }
  })
}

const useStore = create<StoreV2>()(
  persist(
    (set) => ({ user: null as any, settings: { theme: 'light' as const } }),
    {
      name: 'app-store',
      migrate: withMigrations({ version: 2, migrations })
    }
  )
)

Cloud Sync

Real-time sync across devices with Supabase:

import { create } from 'zustand'
import { persist, withCloudSync } from 'zustand-persist-plus'
import { createSupabaseAdapter } from 'zustand-persist-plus/cloud'

const useStore = create()(
  persist(
    withCloudSync(
      createSupabaseAdapter(supabase, 'todos', {
        userId: user.id,
        conflictStrategy: 'last-write-wins'
      })
    )(
      (set) => ({
        todos: [],
        addTodo: (todo) => set((state) => ({ todos: [...state.todos, todo] }))
      })
    ),
    { name: 'todos' }
  )
)

API Reference

Middleware

| Function | Description | |----------|-------------| | withEncryption(secret, options?) | Encrypt persisted data | | withCompression(options?) | Compress persisted data | | withMigrations(config) | Version-based schema migrations | | withCloudSync(adapter, options?) | Real-time cloud sync |

Storage Adapters

// Built-in adapters
import { createIndexedDBAdapter } from 'zustand-persist-plus'
import { createSupabaseAdapter } from 'zustand-persist-plus/cloud'
import { createFirebaseAdapter } from 'zustand-persist-plus/cloud'

Utility Functions

import { encrypt, decrypt, compress, decompress } from 'zustand-persist-plus'

Documentation

• Full Documentation
• Cloud Sync Guide
• Migration Examples
• API Reference

Contributing

Contributions are welcome! Please read our Contributing Guide.

License

MIT License — see LICENSE for details.

Built for developers who care about user data 🔒