Skip to content

Pinia State Management ​

17:43

Use pinia for state shared across pages. uni-app x ships with pinia 3.0.4 built in, so no dependency needs to be installed: mount it with app.use(createPinia()) in main.ts, and every page that calls the same useXxxStore() gets the very same instance.

Mounting ​

ts
// main.ts
import { createSSRApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.uvue'

export function createApp() {
    const app = createSSRApp(App)
    // pinia 3.0.4 is built into uni-app x; the compiler points to the built-in runtime when the project has no pinia dependency
    app.use(createPinia())
    return {
        app
    }
}

No installation required

createPinia resolves to the runtime bundled with uni-app x, so the project compiles and runs fine without a pinia dependency.

Defining a store ​

The setup store style is recommended: ref for state, computed for getters, plain functions for actions, all returned together. TS is strongly typed, so spell out the generics and return types.

ts
// store/counter.ts
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', () => {
    // state
    const name = ref<string>('Pinia')
    const count = ref<number>(0)

    // getters
    const doubleCount = computed((): number => count.value * 2)
    const countText = computed((): string => name.value + ': ' + count.value)

    // actions
    function increment(): void {
        count.value++
    }

    function reset(): void {
        name.value = 'Pinia'
        count.value = 0
    }

    return {
        name,
        count,
        doubleCount,
        countText,
        increment,
        reset
    }
})
PartWritten asNotes
stateref<T>(...)Provide the generic explicitly so it is not inferred as any
gettercomputed((): T => ...)Annotate the return type
actionplain functionMutate ref.value inside; no extra wrapper needed

Using a store in a page ​

ts
// pages/xxx/index.uvue
import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/store/counter.ts'

const counterStore = useCounterStore()
// state / getters must be destructured through storeToRefs; destructuring the store directly loses reactivity
const { name, count, doubleCount, countText } = storeToRefs(counterStore)

function increment(): void {
    counterStore.increment()
}

The template then uses the unwrapped name, count, doubleCount and countText directly. Mutations go through the store's actions (counterStore.increment()); do not mirror the value into local state.

Sharing across pages ​

The store instance is owned by pinia at application level and is independent of page lifecycles:

  • If page A calls increment(), the count unwrapped by storeToRefs on page B updates too — no event bus or route parameter needed;
  • Navigating back or recreating a page does not reset the state; only an action or a fresh application instance changes it;
  • Calling useCounterStore() at the top level of a page's script setup is enough; every page receives the same store.

State lifetime

pinia does not persist state by default, so a restart returns every value to its initial state. If it must survive a restart, write to local storage inside an action and read it back when the store initializes.

Demo page ​

The demo page pages/library/pinia/index.uvue covers the three parts above:

  • Store state: name, count and the two getters, all unwrapped by storeToRefs;
  • Actions: the increment, decrement, rename and reset buttons update the displayed state immediately;
  • Usage notes: mounting, the setup store style, storeToRefs destructuring, and the built-in version.

The matching snippets live in the demo page's code.ts as store, mount and usage, ready to copy.

Notes ​

  1. const { count } = useCounterStore() loses reactivity: state and getters must be destructured through storeToRefs, and actions stay as method calls rather than destructured values.
  2. Do not install pinia separately. uni-app x already bundles 3.0.4, and an installed version may not match the built-in runtime.
  3. With TS being strongly typed, annotate the generics and return types of ref<number>() and computed((): number => ...) explicitly, otherwise an inferred any can fail App-side compilation.
  4. The store id (the first argument of defineStore) must be unique within one application; a duplicate reuses the definition registered later.