useAppStorage

GitHub View source

A Vue composable that manages reactive localStorage or sessionStorage state with type-safe defaults, serialization, and cross-tab sync.

Usage

useAppStorage is a powerful composable built on top of @vueuse/core's useStorage, enabling safe and easy management of the browser's localStorage or sessionStorage.

It automatically handles data serialization and deserialization, and provides reactive state management.

<script setup lang="ts">
import { useAppStorage } from '@movk/core'

// Define the type for user preferences
interface UserPreferences {
  theme: 'light' | 'dark'
  language: string
  notifications: {
    email: boolean
    push: boolean
  }
}

// Create a reactive storage instance
const { state, setItem, getItem, removeItem } = useAppStorage<UserPreferences>({
  key: 'user-preferences',
  defaultValue: {
    theme: 'light',
    language: 'en',
    notifications: {
      email: true,
      push: false
    }
  },
  storage: 'localStorage', // or 'sessionStorage'
  prefix: 'my-app'
})

// Use the reactive state directly in the template or script
console.log(state.value.theme) // 'light'

// Update data
function toggleTheme() {
  setItem({
    ...state.value,
    theme: state.value.theme === 'light' ? 'dark' : 'light'
  })
}

// Update partial data
function enablePushNotifications() {
  setItem({
    ...state.value,
    notifications: {
      ...state.value.notifications,
      push: true
    }
  })
}
</script>

<template>
  <div>
    <p>Current theme: {{ state.theme }}</p>
    <button @click="toggleTheme">
      Toggle theme
    </button>
    <p>Push notifications: {{ state.notifications.push ? 'Enabled' : 'Disabled' }}</p>
    <button @click="enablePushNotifications">
      Enable push notifications
    </button>
  </div>
</template>

When data read from storage cannot be parsed correctly, useAppStorage automatically falls back to defaultValue and prints a warning to the console.

API

`useAppStorage(config)`

Creates and returns a storage instance.

`config` Parameters

key

string required

The unique key name for the storage item.

defaultValue

T required

The default value to use when no valid value exists in storage.

storage

'localStorage' | 'sessionStorage'

The browser storage type to use. Defaults to localStorage.

prefix

string

An optional prefix prepended to the key to create a namespace and avoid key conflicts. The final key will be prefix:key. Defaults to movk.

Returns

useAppStorage returns an object with the following properties:

state

Ref<T>

A reactive ref whose value stays in sync with the stored data. You can read or modify it directly.

getItem

() => T

A function that reads and returns data from storage. Returns defaultValue if the data cannot be parsed.

setItem

(value: T) => void

A function that sets a new value. The new value is serialized before being stored.

removeItem

() => void

A function that removes the item from storage.

Changelog

No recent changes

Agent Skills

@movk/core ships a Claude Agent Skill (SKILL.md) that teaches AI coding agents which utility to reach for and how to use it correctly, alongside the MCP server.

useCopyCode

A Vue composable that copies text to the clipboard using the async Clipboard API, with a legacy execCommand fallback for older browsers.