@runablejs/Pinia

@runablejs/pinia creates a fresh Pinia instance for every Runable application. Stores, Pinia helpers, and files exported from app/stores are available through auto-imports, with no application plugin to configure manually.

Installation

Install the Runable module and Pinia:

pnpm add @runablejs/pinia pinia

Then register the module in runable.config.ts:

import { defineConfig } from "runable";

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

Create a store

Create app/stores/counter.ts. defineStore is auto-imported:

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

The exported store is auto-imported in components and composables:

<script setup lang="ts">
const counter = useCounterStore();
const { count } = storeToRefs(counter);
</script>

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

Options

Scan additional store directories

Use storeDirs when stores live outside app/stores. 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.

Persist a store

Persistence uses Unstorage. Enable it on an individual store:

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

Use a custom key when the store identifier should not be used for storage:

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

Hydration is asynchronous. Await $persistReady before reading restored state in code that must wait for persistence:

const preferences = usePreferencesStore();

await preferences.$persistReady;
await preferences.$persist();
await preferences.$hydrate();

Configure persistence globally

Enable persistence for every store and choose between local and session storage from runable.config.ts:

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

Set persist: false on a store to opt out when global persistence is enabled. You can also provide a custom Unstorage driver through pinia.unstorage.driver.

During SSR, each request receives an isolated Pinia instance and an isolated in-memory persistence store. Browser storage is only used on the client.