pinia

library3.0.4jsnpmunverified

Pinia is an intuitive, type-safe, and flexible state management library specifically designed for Vue.js applications. It serves as a lightweight and robust alternative to Vuex, leveraging Vue 3's Composition API for a more modern and streamlined development experience. The current stable major version is v3.x, with the latest release being v3.0.4, indicating active maintenance and minor updates within the major release. Pinia distinguishes itself through its excellent TypeScript support, providing strong type inference out-of-the-box, automatic module generation (no need for nested modules), and a plugin system. Its API is designed to be straightforward and familiar to Vue developers, making state management less verbose and more declarative. Releases within a major version (like v3.0.x) typically include bug fixes and minor improvements, with major version bumps (v2 to v3) often aligning with Vue major version releases and dropping support for older ecosystems (e.g., Vue 2).

web-framework

npm install pinia

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PINIA

pinia

web-frameworkjavascriptv3.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createPinia

✓ import { createPinia } from 'pinia'

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

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

defineStore

✓ import { defineStore } from 'pinia'

✗ 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

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

✗ import { useStore } from 'pinia';

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`.

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>';

Debug

Known issues

breakingPinia 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.

affects: >=3.0.0

breakingPinia 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`).

affects: >=3.0.0

breakingThe `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.

affects: >=3.0.0

gotchaEnsure `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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'.

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`).

Upgrade

Version history

3.0.4latest on npm

Audit

Dependencies

typescriptrequiredRequired for type-safe usage, especially since v3.0.0 leverages native Awaited which needs TS >=4.5.0.

vuerequiredPinia is a state management library for Vue.js applications.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/vuejs/pinia ↗

packagehttps://www.npmjs.com/package/pinia ↗

homepagehttps://pinia.vuejs.org ↗