Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Installing and Setting Up Pinia

Install Pinia with npm or create-vue, register createPinia with app.use, learn the recommended folder layout and how the live examples on this site load Pinia from a CDN.

Setting up Pinia takes three steps: install the package, create a Pinia instance, and give it to your Vue app. After that, every component can use stores. This lesson walks through each step for a real project, then explains the slightly different setup the live examples on this site use.

Requirements

Pinia 3 works with Vue 3.5 or newer and no longer supports Vue 2 or the old vue-demi bridge. If you must stay on Vue 2, use Pinia 2. For new projects, Pinia 3 is the right choice, and it is what this tutorial uses.

You also need a build tool for a normal project. The standard one is Vite. If you have no project yet, create one with Vue's official scaffolding command:

Terminal
npm create vue@latest

The wizard asks which features you want. Answer Yes to "Add Pinia for state management" and it configures everything below for you. To add Pinia to an existing project instead, install it:

Terminal
npm install pinia

Other package managers work the same way: pnpm add pinia, yarn add pinia or bun add pinia.

Creating the Pinia instance

The Pinia instance (often just called "the pinia") is the container that holds every store of one application. You create it with createPinia() and install it with app.use(), exactly like a Vue plugin:

JavaScript
// src/main.js
import { createApp } from "vue";
import { createPinia } from "pinia";
import App from "./App.vue";

const app = createApp(App);
const pinia = createPinia();

app.use(pinia);
app.mount("#app");

The order matters a little: call app.use(pinia) before any component tries to use a store, which in practice means before mount(). Most projects write the compact form:

JavaScript
createApp(App).use(createPinia()).mount("#app");

Why is the instance separate from the stores? Because it belongs to the app, not to the JavaScript module. Each app gets its own stores, and on a server each request can get its own as well (see SSR and Nuxt later in the course). A module-level singleton could not do that.

flowchart LR
    A["createPinia()"] --> B["app.use(pinia)"]
    B --> C["useCounterStore()"]
    C --> D["Store created lazily<br/>and stored in the pinia"]
    D --> E["Same store for every later call"]

Stores are created lazily: the first call of useXxxStore() builds the store inside the installed pinia, and later calls return that same object.

Pinia does not force a folder structure, but this layout is a common and tidy convention:

TEXT
src/
  main.js
  App.vue
  stores/
    counter.js
    cart.js
    user.js
  components/
  views/

Each file in stores/ holds one store and exports a function named useSomethingStore. The name pattern use...Store is a convention shared with Vue composables, and it tells readers that calling it gives you a store.

JavaScript
// src/stores/counter.js
import { defineStore } from "pinia";

export const useCounterStore = defineStore("counter", {
  state: () => ({ count: 0 }),
});

In a component you import and call it inside <script setup>:

VUE
<script setup>
import { useCounterStore } from "@/stores/counter";

const counter = useCounterStore();
</script>

<template>
  <p>{{ counter.count }}</p>
</template>

How the live examples load Pinia

The runnable examples in this tutorial cannot use npm or a bundler. They run in a sandboxed preview, so they load Vue and Pinia as ES modules from a CDN and use an import map that tells the browser what "vue" and "pinia" mean:

HTML
<script type="importmap">
  { "imports": {
      "vue": "https://cdn.jsdelivr.net/npm/[email protected]/dist/vue.esm-browser.prod.js",
      "pinia": "https://esm.sh/[email protected]?external=vue" } }
</script>

Two details are worth knowing:

  1. ?external=vue tells the CDN not to bundle its own copy of Vue into Pinia. Pinia must share the same Vue instance as your app, otherwise reactivity breaks silently.
  2. The full Vue build (vue.esm-browser.prod.js) includes the template compiler, so we can write template: strings in plain objects. In a real project, .vue files are compiled ahead of time and you would not need it.

The preview sandbox also blocks localStorage, and Pinia's DevTools helper checks it while loading. So each example starts with a short script that adds an empty stand-in when the real one is unavailable. You will not need that in your own project.

Here is the full minimal setup as a runnable page. The first lines of the editor are exactly this plumbing, followed by your own code.

Minimal Pinia setup from a CDN

Type in the field: the greeting updates, because v-model writes straight into the store's state. The console line confirms that app.use(pinia) made it the active instance.

What happens if you forget app.use(pinia)?

Calling a store function without an installed pinia throws an error. A development build explains that there is no active Pinia; the production build used by the live examples gives a terser message. Try it: the code below creates a store and uses it before any pinia exists, then installs one and tries again.

Using a store before installing Pinia

setActivePinia is useful in tests and scripts where no app exists. You will use it again in the testing chapter.

The classic setup mistake is calling useStore() at the top level of a module that is imported before app.use(pinia) runs. Call stores inside functions, setup(), or <script setup>, so they run after installation. Using Stores Outside Components shows the safe patterns.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does createPinia() return?

    The pinia instance is the container. Stores are created lazily inside it the first time you call their use function.
  2. 2. Which Vue version does Pinia 3 require?

    Pinia 3 dropped Vue 2 support and vue-demi, and needs Vue 3.5 or newer.
  3. 3. Why do the CDN examples add ?external=vue to the Pinia URL?

    Two copies of Vue would not share reactivity, so Pinia state would stop updating components.
  4. 4. Where should you call app.use(pinia)?

    Stores need an installed pinia, so install it before components that use stores are created.

Summary

  • Install with npm create vue@latest (tick Pinia) or npm install pinia.
  • Create one instance with createPinia() and install it with app.use(pinia) before mounting.
  • Keep stores in src/stores/, one file per store, named useXxxStore.
  • Stores are created lazily and cached inside the pinia of the app.
  • The live examples use an import map, a shared Vue copy (?external=vue) and a tiny localStorage stand-in because of the preview sandbox.

Next: Your First Store