Pinia: The Intuitive Store for Vue

Common errors

• TypeError: Cannot read properties of undefined (reading 'install')

  cause Pinia (or another plugin) was not installed correctly with `app.use()`.
  fix Ensure `app.use(createPinia())` is called correctly on your Vue application instance before mounting.

• Error: [pinia]: Missing Pinia plugin. Ensure 'app.use(createPinia())' is called.

  cause Attempting to use `defineStore` or `useMyStore` composables before Pinia has been installed on the Vue application.
  fix Add `app.use(createPinia())` to your application's entry point before any component using Pinia is initialized.

• Type 'T' does not satisfy the constraint 'object'.

  cause TypeScript version is older than 4.5.0, which is required by Pinia v3.0.0 for its use of the `Awaited` utility type.
  fix Upgrade TypeScript to version 4.5.0 or higher in your project dependencies (`npm install -D typescript@latest`).

Warnings

• breaking Pinia v3.0.0 drops support for Vue 2. If you are using Vue 2, you must remain on Pinia v2.x.
  Fix: Upgrade your Vue application to Vue 3 or stick to Pinia v2.x. Refer to the official migration guide for v2 to v3.
• breaking Pinia v3.0.0 requires TypeScript version >=4.5.0 due to its internal use of the native `Awaited` type. Projects with older TypeScript versions will encounter compilation errors.
  Fix: Update your project's TypeScript dependency to 4.5.0 or newer (e.g., `npm install -D typescript@latest`).
• breaking The `PiniaStorePlugin` API has been removed in Pinia v3.0.0. Developers using custom plugins need to adapt to the new plugin system, which likely involves using `PiniaPlugin`.
  Fix: Consult the Pinia v3 documentation on writing plugins. The migration guide from v2 to v3 provides details on this change.
• gotcha Ensure `app.use(pinia)` is called *before* you try to access any stores within your components' `setup` functions or lifecycle hooks, otherwise stores will not be available.
  Fix: Always initialize and install Pinia as a Vue plugin (`app.use(createPinia())`) at the root of your application before any component that consumes a store is mounted.

Install

• npm install pinia npm
• yarn add pinia yarn
• pnpm add pinia pnpm

Imports

• createPinia
  wrong:

  const { createPinia } = require('pinia');

  correct:

  import { createPinia } from 'pinia'

  Pinia is primarily used with ESM. `createPinia` initializes the Pinia store for your Vue app.
• defineStore
  wrong:

  import defineStore from 'pinia';

  correct:

  import { defineStore } from 'pinia'

  `defineStore` is a named export used to create individual stores. It is not a default export.
• Store

  import type { Store } from 'pinia'

  When importing types like `Store` or `Pinia`, use `import type` for better tree-shaking and explicit type import semantics in TypeScript.
• useStore
  wrong:

  import { useStore } from 'pinia';

  correct:

  import { useMyStore } from './stores/myStore'

  While `defineStore` is imported from 'pinia', the specific `useMyStore` composable function is exported from *your own store file* (e.g., `stores/myStore.ts`) after defining it with `defineStore`.

Quickstart

This quickstart demonstrates how to set up Pinia in a Vue 3 application, define a basic store with state, getters, and actions, and use it within a Vue component.

import { createApp } from 'vue';
import { createPinia, defineStore } from 'pinia';

const app = createApp({
  template: `
    <div>
      <h1>Counter: {{ counter }}</h1>
      <p>Double Counter: {{ doubleCounter }}</p>
      <button @click="increment">Increment</button>
      <button @click="reset">Reset</button>
    </div>
  `,
  setup() {
    const main = useMainStore();
    return {
      counter: main.counter,
      doubleCounter: main.doubleCounter,
      increment: main.increment,
      reset: main.reset
    };
  }
});

// Define a Pinia store
const useMainStore = defineStore('main', {
  state: () => ({
    counter: 0,
    name: 'Pinia Example'
  }),
  getters: {
    doubleCounter: (state) => state.counter * 2
  },
  actions: {
    increment() {
      this.counter++;
    },
    reset() {
      this.counter = 0;
    }
  }
});

const pinia = createPinia();
app.use(pinia);
app.mount('#app');

// To make it runnable in a simple environment, assume an #app div exists:
document.body.innerHTML = '<div id="app"></div>';