Pinia State Management

Pinia is a state management library for Vue that allows you to share state across components and pages. While you can share state using a simple reactive object in Single Page Applications (SPAs), Pinia provides essential features for production-grade applications, especially those using Server Side Rendering (SSR) to prevent cross-request state pollution.

Key benefits include:

• Testing utilities: Built-in support for testing stores.
• Plugins: Ability to extend Pinia's core features.
• TypeScript/Autocompletion: Excellent support for TS and autocompletion for JS users.
• SSR Support: Safe state management for server-side rendered applications.
• Devtools Support: A timeline to track actions/mutations, visibility of stores in components, and time-travel debugging.
• Hot Module Replacement (HMR): Modify stores without reloading the page while preserving existing state.

In Setup stores, stubbing actions has a limitation: if one action calls another action using a closed-over function reference (instead of via the store instance), the stub will be bypassed and the real implementation will run.

Incorrect (Setup Store):

export const useCounterStore = defineStore('counter', () => {
  function increment() { /* ... */ }
  function incrementTwice() {
    increment() // ❌ Uses closed-over reference; stub is ignored
  }
  return { increment, incrementTwice }
})

Correct (Setup Store): To make internal calls stubbable, route them through the store instance:

export const useCounterStore = defineStore('counter', () => {
  function increment() { /* ... */ }
  function incrementTwice() {
    const store = useCounterStore()
    store.increment() // ✅ Uses the store instance; stub is used
  }
  return { increment, incrementTwice }
})

Note: Options stores do not have this limitation because internal calls use this, which refers to the store instance.

Setup Stores use a syntax similar to Vue's Composition API. You pass a setup function that defines reactive properties and methods, then returns an object containing what you want to expose.

• ref() calls become state properties.
• computed() calls become getters.
• function() calls become actions.

Important Requirements:

• You must return all state properties in the return object. Failing to return state properties or making them readonly will break SSR, devtools, and other plugins.
• Setup stores allow you to use watchers and other composables inside the store.
• You can access globally provided properties (like Router or Route) using inject() within a setup store.

Warning: Do not return non-store properties (like route or injected app-level values) in the return object; access them directly in components instead.

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const name = ref('Eduardo')
  const doubleCount = computed(() => count.value * 2)
  function increment() {
    count.value++
  }

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

Actions are the Pinia equivalent of component methods and are the primary place to define business logic. They can be synchronous or asynchronous.

Key characteristics:

• Access to Store: Actions have access to the entire store instance via this with full type support and autocompletion.
• Asynchronous Support: Unlike getters, actions can be async and can await API calls or other actions.
• No Arrow Functions: Because actions rely on this to access the store state and other actions, you cannot use arrow functions for the action definitions themselves.
• Flexibility: You can define any arguments and return values; Pinia automatically infers types when calling them.

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    // Use regular functions to ensure `this` is bound correctly
    increment() {
      this.count++
    },
    async asyncIncrement() {
      const result = await someApiCall()
      this.count += result
    }
  },
})

When two or more stores use each other, you must ensure they do not create an infinite loop through getters or actions. Specifically, stores that depend on each other cannot both directly read each other's state within their setup function.

To avoid this, access properties of the other store within computed properties or actions instead of at the top level of the setup function.

const useX = defineStore('x', () => {
  const y = useY()

  // ❌ This is not possible because y also tries to read x.name
  y.name

  function doSomething() {
    // ✅ Read y properties in computed or actions
    const yName = y.name
    // ...
  }

  return {
    name: ref('I am X'),
  }
})

const useY = defineStore('y', () => {
  const x = useX()

  // ❌ This is not possible because x also tries to read y.name
  x.name

  function doSomething() {
    // ✅ Read x properties in computed or actions
    const xName = x.name
    // ...
  }

  return {
    name: ref('I am Y'),
  }
})