Advanced Usage

TypeScript types

All public types are exported from the package root:

import type {
  // Storage targets
  StorageTarget, // 'local' | 'session' | 'memory' | 'indexeddb'

  // Core options
  StorageOptions,
  CookieOptions,
  EncryptOptions,
  SignOptions,
  CompressOptions,
  SyncOptions,

  // Migration
  Migration,

  // Serializer interface
  Serializer,

  // Internal envelope structure
  StorageEnvelope,

  // Error union
  StorageError,
  // { type: 'quota-exceeded'; key }
  // { type: 'parse-error'; key; raw }
  // { type: 'migration-failed'; from; to; error }
  // { type: 'crypto-error'; operation; error }
  // { type: 'write-failed'; key; error }
  // { type: 'signature-invalid'; key }
  // { type: 'read-failed'; key; error }

  // Low-level adapter interface (all methods return Promises)
  StorageAdapter,

  // Return types
  UseStorageReturn,
  UseIndexedDBReturn,
  UseIDBRefReturn,

  // Plugin options
  VueStoragePluginOptions,
} from 'vue-storage-kit'

StorageError discriminated union:

import type { StorageError } from 'vue-storage-kit'

function handleError(err: StorageError) {
  switch (err.type) {
    case 'quota-exceeded':
      console.error('Storage full, key:', err.key)
      break
    case 'parse-error':
      console.error('Could not parse', err.key, '— raw:', err.raw)
      break
    case 'migration-failed':
      console.error(`Migration ${err.from} → ${err.to} failed:`, err.error)
      break
    case 'crypto-error':
      console.error(`Crypto ${err.operation} failed:`, err.error)
      break
    case 'signature-invalid':
      console.error('Tampered or corrupted signed value:', err.key)
      break
    case 'write-failed':
      console.error('Non-quota write failure:', err.key, err.error)
      break
    case 'read-failed':
      console.error('Could not read from storage:', err.key, err.error)
      break
  }
}

Custom serializer type:

import type { Serializer } from 'vue-storage-kit'

const msgpack: Serializer<unknown> = {
  serialize: (v) => Buffer.from(encode(v)).toString('base64'),
  deserialize: (s) => decode(Buffer.from(s, 'base64')),
}

SSR compatibility

Scenario	Behaviour
typeof window === 'undefined'	All adapters fall back to MemoryStorageAdapter (in-process, not persisted)
isReady.value === false	The composable has not yet read from storage; show a skeleton or v-if="isReady"
useCookie on server (Nuxt)	The vue-storage-kit/nuxt module auto-imports an SSR-aware useCookie() that reads from event.node.req.headers.cookie and writes httpOnly cookies via H3's setCookie(). The base useCookie exported from vue-storage-kit directly (used outside Nuxt, or without the module) is client-only — document.cookie is unavailable on the server, so it returns defaultValue during SSR
Hydration mismatch	useStorage re-reads the actual client value after mount — the SSR-rendered value is never used on the client

<script setup lang="ts">
const { value: prefs, isReady } = useLocalStorage('prefs', { theme: 'light' })
</script>

<template>
  <SkeletonCard v-if="!isReady" />
  <UserPrefs v-else :prefs="prefs" />
</template>