XDS

Appearance

Persistence ​

XDS provides a built-in persistence plugin that makes it easy to save store state to localStorage, sessionStorage, or any custom storage engine.

Installation ​

The persistence plugin is provided via the persistence factory function. You can register it globally when installing XDS.

typescript
import { createApp } from 'vue'
import { xds, persistence } from 'xds'

const app = createApp(App)

app.use(
  xds({
    plugins: [
      persistence({
        // Configuration options
        enable: ['counter', 'auth'], // List of store IDs to persist
      }),
    ],
  }),
)

Configuration ​

The persistence function accepts an options object with the following properties:

enable ​

  • Type: string[] | ((id: string) => boolean)
  • Description: Determines which stores should be persisted. You can pass an array of store IDs or a function that returns true for stores that should be persisted.

defaultStrategy ​

  • Type: PersistenceStrategy
  • Description: The default persistence strategy applied to all enabled stores.

strategies ​

  • Type: Record<string, PersistenceStrategy>
  • Description: Per-store strategy overrides. Keys are store IDs.

Persistence Strategy ​

A strategy object configures how a specific store is persisted.

typescript
interface PersistenceStrategy {
  key?: string // Storage key (default: store.$id)
  storage?: StorageLike // Storage engine (default: localStorage)
  paths?: string[] // Whitelist: only persist these paths
  omit?: string[] // Blacklist: persist everything except these paths
  serializer?: Serializer // Custom serializer (default: JSON)
  debug?: boolean // Enable debug logs
  version?: number // Data version for migration
  migrate?: (oldState: any, oldVersion: number) => StateTree // Migration function
}

Examples ​

Basic Usage ​

Persist the 'counter' store to localStorage.

typescript
app.use(
  xds({
    plugins: [
      persistence({
        enable: ['counter'],
      }),
    ],
  }),
)

Using sessionStorage ​

typescript
app.use(
  xds({
    plugins: [
      persistence({
        enable: ['session-data'],
        defaultStrategy: {
          storage: sessionStorage,
        },
      }),
    ],
  }),
)

Partial Persistence (Whitelist) ​

Only persist the token and user fields of the auth store.

typescript
app.use(
  xds({
    plugins: [
      persistence({
        enable: ['auth'],
        strategies: {
          auth: {
            paths: ['token', 'user'],
          },
        },
      }),
    ],
  }),
)

Different Configuration per Store ​

You can apply different persistence strategies to different stores using the strategies option. For example, persisting only the token for aStore and boken for bStore.

typescript
app.use(
  xds({
    plugins: [
      persistence({
        enable: ['aStore', 'bStore'],
        strategies: {
          aStore: {
            paths: ['token'], // Only persist 'token' for aStore
          },
          bStore: {
            paths: ['boken'], // Only persist 'boken' for bStore
          },
        },
      }),
    ],
  }),
)

Versioning and Migration ​

Handle state structure changes with versioning.

typescript
app.use(
  xds({
    plugins: [
      persistence({
        enable: ['settings'],
        strategies: {
          settings: {
            version: 2,
            migrate: (state, oldVersion) => {
              if (oldVersion === 1) {
                // Rename 'theme' to 'appearance'
                return { ...state, appearance: state.theme }
              }
              return state
            },
          },
        },
      }),
    ],
  }),
)

Manual Watch (Legacy) ​

If you prefer full control, you can still use Vue's watch manually.

typescript
import { watch } from 'vue'

watch(
  () => store.$state,
  (state) => {
    localStorage.setItem('myState', JSON.stringify(state))
  },
  { deep: true },
)