Pinia State Management
17:43Use 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
// 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.
// 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
}
})| Part | Written as | Notes |
|---|---|---|
| state | ref<T>(...) | Provide the generic explicitly so it is not inferred as any |
| getter | computed((): T => ...) | Annotate the return type |
| action | plain function | Mutate ref.value inside; no extra wrapper needed |
Using a store in a page
// 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(), thecountunwrapped bystoreToRefson 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'sscript setupis 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,countand the two getters, all unwrapped bystoreToRefs; - Actions: the
increment,decrement,renameandresetbuttons update the displayed state immediately; - Usage notes: mounting, the setup store style,
storeToRefsdestructuring, 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
const { count } = useCounterStore()loses reactivity: state and getters must be destructured throughstoreToRefs, and actions stay as method calls rather than destructured values.- Do not install pinia separately. uni-app x already bundles 3.0.4, and an installed version may not match the built-in runtime.
- With TS being strongly typed, annotate the generics and return types of
ref<number>()andcomputed((): number => ...)explicitly, otherwise an inferredanycan fail App-side compilation. - The store
id(the first argument ofdefineStore) must be unique within one application; a duplicate reuses the definition registered later.