Runable Pinia

Official Pinia state management integration for Runable ⚡️

Description

@runablejs/pinia installs a fresh Pinia instance in every Runable Vue application. Stores work in components and composables with no application plugin to configure manually.

Features

• 🍍 Pinia 3 support
• ⚡️ Zero-configuration Runable integration
• 📦 Automatic store and Pinia helper imports
• 💾 Optional persistence powered by Unstorage
• 🔌 Custom Unstorage driver support
• 🔒 One isolated Pinia instance per application and SSR request
• 💚 Vue 3 and TypeScript ready

Installation

pnpm add @runablejs/pinia pinia

Add the module to runable.config.ts:

import { defineConfig } from "runable";

export default defineConfig({
  modules: ["@runablejs/pinia"],
});

Usage

Create a store, for example in app/stores/counter.ts. defineStore is auto-imported:

export const useCounterStore = defineStore("counter", {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++;
    },
  },
});

Stores exported from app/stores are auto-imported too:

<script setup lang="ts">
const counter = useCounterStore();
</script>

<template>
  <button type="button" @click="counter.increment()">
    Count: {{ counter.count }}
  </button>
</template>

Pinia helpers such as storeToRefs are also available without imports:

const counter = useCounterStore();
const { count } = storeToRefs(counter);

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | storeDirs | string[] | ['{appDir}/stores'] | Directories containing stores to auto-import. | | persist | boolean | false | Persist every store by default. | | unstorage | UnstorageOptions | See below | Configure the persistence storage. |

Unstorage options

| Option | Type | Default | Description | | --- | --- | --- | --- | | namespace | string | 'runable:pinia:' | Prefix used to isolate persisted store keys. | | windowKey | 'localStorage' \| 'sessionStorage' | 'localStorage' | Browser storage backend. | | driver | Driver \| (() => Driver) | Browser local storage | Custom Unstorage driver or driver factory. |

Store directories

Stores exported from {appDir}/stores are auto-imported by default, so they can be used without an explicit import:

<script setup lang="ts">
const counter = useCounterStore();
</script>

Use storeDirs to scan additional directories. Paths are relative to the Runable project root:

import { defineConfig } from "runable";

export default defineConfig({
  modules: ["@runablejs/pinia"],
  pinia: {
    storeDirs: ["app/stores", "features/account/stores"],
  },
});

Setting storeDirs replaces the default list.

Store persistence

Persistence is powered by Unstorage. It uses localStorage in the browser and isolated memory during server rendering. Enable it per store:

export const usePreferencesStore = defineStore("preferences", {
  state: () => ({ theme: "light" }),
  persist: true,
});

A custom key can be configured per store:

export const usePreferencesStore = defineStore("preferences", {
  state: () => ({ theme: "light" }),
  persist: {
    key: "user-preferences",
  },
});

Hydration is asynchronous. Await $persistReady when code needs the restored state before continuing:

const preferences = usePreferencesStore();

await preferences.$persistReady;
await preferences.$persist(); // save immediately
await preferences.$hydrate(); // reload from storage

Persistence can also be enabled for every store from runable.config.ts and the Unstorage browser driver can be configured globally:

export default defineConfig({
  modules: ["@runablejs/pinia"],
  pinia: {
    persist: true,
    unstorage: {
      namespace: "my-app:pinia:",
      windowKey: "sessionStorage",
    },
  },
});

Set persist: false on an individual store to opt out when global persistence is enabled.

Custom Unstorage driver

Pass any Unstorage driver instance or a factory. A factory is useful when the driver should be created lazily:

import memoryDriver from "unstorage/drivers/memory";
import { defineConfig } from "runable";

export default defineConfig({
  modules: ["@runablejs/pinia"],
  pinia: {
    persist: true,
    unstorage: {
      namespace: "my-app:pinia:",
      driver: () => memoryDriver(),
    },
  },
});

When no custom driver is provided, the module uses localStorage or sessionStorage in the browser and an isolated in-memory storage during SSR.

Contributing

See CONTRIBUTING.md for local setup, tests, changesets, and the pull request checklist.

License

MIT