xds

A lightweight, Pinia-like state management library for Vue 3. It provides a simple Setup Store pattern with built-in persistence support and essential helpers.

Features

• 📦 Lightweight: Zero dependencies (only Vue).
• ⚡ Reactive: Built on Vue 3's Reactivity API.
• 🛠 Setup Stores: Define stores using standard Vue Composition API.
• 🔌 Pinia Compatible API: Familiar methods like $patch, $reset, $state.
• 🧩 No Boilerplate: No actions/mutations separation. Just functions.
• 🔧 TypeScript: First-class type support.

Installation

npm install xds
# or
pnpm add xds

Usage

1. Install Plugin (Recommended)

For sharing state across your app and ensuring SSR/Multi-app isolation, install the plugin:

import { createApp } from 'vue'
import { xds } from 'xds'
import App from './App.vue'

const app = createApp(App)
app.use(xds())
app.mount('#app')

2. Define a Store

xds uses the Setup Store pattern. You define state using ref or reactive, and actions as regular functions.

import { defineStore } from 'xds'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  // State
  const count = ref(0)
  const name = ref('Eduardo')

  // Getters
  const doubleCount = computed(() => count.value * 2)

  // Actions
  function increment() {
    count.value++
  }

  function $reset() {
    count.value = 0
  }

  return { count, name, doubleCount, increment, $reset }
})

3. Use in Component

<script setup>
import { useCounterStore } from './store'
import { storeToRefs } from 'xds'

const store = useCounterStore()

// Destructuring with reactivity
const { count, doubleCount } = storeToRefs(store)

function add() {
  store.increment()
}
</script>

<template>
  <button @click="add">Count: {{ count }} (Double: {{ doubleCount }})</button>
</template>

Core Concepts & Guide

defineStore (Hook Pattern)

• defineStore: Returns a hook function (e.g., useStore).
  • When to use: In most application code, especially within Vue components. It follows the standard Vue/Pinia pattern and allows for lazy initialization. The store is created only when useStore() is first called.
  • Example: const useStore = defineStore(...) → const store = useStore()

Plugin Installation

Installing the plugin via app.use(xds()) is strongly recommended for modern Vue apps.

• Why use it: It ensures the store registry is properly provided to your application context.
  • SSR Safe: Essential for preventing state pollution between requests in Server-Side Rendering.
  • State Isolation: Ensures isolated store instances for multiple Vue apps on the same page.
  • Leak Detection: The library warns if you use defineStore without an active registry context (when xds is used).
• Without it: Stores fall back to a global module-level registry (Singleton Mode), which is simpler but less safe for complex environments.

API Reference

Detailed API documentation is available in the online documentation.

Core Methods

• $patch(partialStateOrMutator): Update state.
• $reset(): Reset state (requires implementation).
• $state: Access or replace the entire state object.
• $dispose(): Stop the store's effect scope.

Core Functions

• defineStore(id, setup): Create a hook to access a store.
• xds(): Create a new store registry for the app.

Utilities

• storeToRefs(store): Destructures state while preserving reactivity.

Persistence

XDS includes a powerful built-in persistence plugin.

Setup

Register the plugin in your app entry point:

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

const app = createApp(App)

app.use(
  xds({
    plugins: [
      persistence({
        // Enable persistence for specific stores by ID
        enable: ['counter', 'auth'],
      }),
    ],
  }),
)

Advanced Configuration (Per-Store)

You can customize persistence behavior for each store using strategies. For example, persisting different keys for different stores:

persistence({
  enable: ['aStore', 'bStore'],
  strategies: {
    aStore: {
      paths: ['token'], // Only persist 'token' for aStore
    },
    bStore: {
      paths: ['boken'], // Only persist 'boken' for bStore
      storage: sessionStorage, // Use sessionStorage for this store
    },
  },
})

For full documentation, visit the Persistence Guide.

Development

Scripts

• pnpm build: Build the library
• pnpm test: Run tests (Vitest)
• pnpm test:coverage: Run tests with coverage
• pnpm lint: Lint code
• pnpm format: Format code

License

MIT