Pinia per Vue 3 — State Management Moderno che Finalmente Non Fa Rimpiangere Vuex

Il tuo progetto Vue 3 sta crescendo. I componenti passano props in cascata, gli eventi si inseguono tra padre e figlio, e quella variabile globale condivisa che hai messo su un reactive() fuori da qualsiasi componente ti sta già facendo sudare freddo. Serve uno state management centralizzato. La scelta classica era Vuex. Ma con l'arrivo della Composition API, Vuex ha iniziato a mostrare i suoi anni. Ecco perché nel 2026 la risposta si chiama Pinia.

Noi, di Meteora Web, abbiamo migrato diversi progetti da Vuex a Pinia — e non torneremo indietro. In questa guida ti spieghiamo cos'è, come si usa e perché conviene. Con esempi reali, non teoria.

Cos'è Pinia e perché sostituisce Vuex?

Pinia è una libreria di state management per Vue 3 sviluppata da Eduardo San Martin Morote, lo stesso autore del modulo di Vuex. Non è un'alternativa: è l'erede ufficiale. Integrata nativamente con Vue DevTools, supporta Composition API fin dalla nascita, ed elimina tutta la verbosità di Vuex (mutations, namespacing forzato, store annidati).

La differenza sostanziale? In Pinia non esistono le mutations. Si agisce direttamente sul state con azioni, che possono essere sincrone o asincrone. Il tutto con TypeScript first class citizen. E la struttura è flat: ogni store è un modulo indipendente, senza dover usare 'namespaced: true' come in Vuex.

Perché abbiamo abbandonato Vuex

Vuex è nato per Vue 2, dove la sintassi era basata su oggetti e opzioni. Con Vue 3 e Composition API, si poteva usare ma era un ibrido scomodo. Pinia invece è stato progettato per Vue 3, e si sposa perfettamente con la Composition API. Se vuoi approfondire le basi di Vue 3, ti rimandiamo alla nostra guida sul Vue.js 3 e Composition API.

Come si installa e configura Pinia in un progetto Vue 3?

L'installazione è una riga di terminale. Poi devi registrare il plugin nell'app principale.

npm install pinia
# oppure
yarn add pinia

// main.js / main.ts
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')

Fatto. Ora puoi creare store in qualsiasi file. Di default Pinia usa il singleton pattern: una volta creato uno store, viene riutilizzato automaticamente.

Come definire uno store con Pinia e Composition API?

Ci sono due modi per definire uno store: con l'opzione setup store (il nostro preferito) o con l'Options API. Qui vediamo lo stile Composition API, che è più flessibile e si integra perfettamente con il resto del codice.

// stores/counter.js
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  // State
  const count = ref(0)
  
  // Getters (derivati)
  const doubleCount = computed(() => count.value * 2)
  
  // Actions
  function increment() {
    count.value++
  }
  
  async function fetchAndSet() {
    const response = await fetch('/api/count')
    const data = await response.json()
    count.value = data.value
  }
  
  return { count, doubleCount, increment, fetchAndSet }
})

Nota la sintassi: defineStore prende due argomenti — il nome univoco dello store e una funzione setup. Dentro usi ref per lo state, computed per i getters, e funzioni normali per le actions. Tutto ciò che ritorni sarà accessibile dal componente.

Come usare il store in un componente Vue 3?

Semplicissimo: chiami il composable useCounterStore dentro setup() o nel <script setup>.

<script setup>
import { useCounterStore } from '@/stores/counter'

const store = useCounterStore()
</script>

<template>
  <div>
    <p>Count: {{ store.count }}</p>
    <p>Double: {{ store.doubleCount }}</p>
    <button @click="store.increment()">+</button>
  </div>
</template>

Nessun mapState o mapActions. L'oggetto store è reattivo e puoi accedervi direttamente. Attenzione: per non perdere reattività quando destrutturi, usa storeToRefs se vuoi estrarre singole proprietà.

import { storeToRefs } from 'pinia'
const { count, doubleCount } = storeToRefs(store)
// count e doubleCount sono ReF, non semplici values
const { increment } = store // le azioni si possono destrutturare tranquillamente

Come gestire azioni asincrone e chiamate API con Pinia?

Una delle forze di Pinia è che le azioni possono essere async senza alcuna configurazione extra. Nel nostro esempio fetchAndSet è già un'azione asincrona. La puoi chiamare direttamente dal componente come store.fetchAndSet(). Niente mutations, niente commit: setta direttamente lo state, e la UI si aggiorna automaticamente. Questo taglia del 50% il boilerplate rispetto a Vuex.

Pinia supporta TypeScript meglio di Vuex?

Decisamente sì. Pinia è scritto in TypeScript e fornisce inferenza automatica dei tipi. Se definisci lo store con una funzione setup, i tipi dei parametri e dei valori di ritorno vengono dedotti senza bisogno di interfacce aggiuntive. In Vuex dovevi dichiarare manualmente i tipi per state, getters e mutations. Con Pinia, defineStore restituisce un composable tipizzato — usalo in componenti TypeScript e avrai autocompletamento e controllo a compile-time.

// counter.ts
interface CounterState {
  count: number
}

export const useCounterStore = defineStore('counter', () => {
  const count = ref<number>(0)
  // ...
})

TypeScript funziona out of the box. Se vuoi vedere un esempio pratico di integrazione TypeScript con Vue 3, dai un'occhiata alla nostra pagina sul Vue.js 3 e Composition API.

Come persistire lo stato di Pinia (localStorage, sessionStorage)?

Pinia non include plugin di persistenza nel core, ma ha un ecosistema di plugin. Il più usato è pinia-plugin-persistedstate. Installalo e configuralo una volta.

npm install pinia-plugin-persistedstate

// main.js
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

Poi nello store, aggiungi la proprietà persist: true nella definizione:

export const useAuthStore = defineStore('auth', {
  state: () => ({ token: null }),
  persist: true, // salva automaticamente in localStorage
  // ...
})
// Oppure con setup store:
export const useAuthStore = defineStore('auth', () => {
  const token = ref(null)
  return { token }
}, { persist: true })

Puoi personalizzare la chiave, lo storage e la serializzazione. Per progetti semplici, basta così.

Quali sono gli errori comuni quando si passa da Vuex a Pinia?

Il più frequente? Destrutturare lo store senza usare storeToRefs. Vuex restituiva oggetti reattivi, ma con Pinia se fai const { count } = store, perdi la reattività. Usa sempre storeToRefs per lo state e i getters. Le azioni si possono destrutturare liberamente.

Secondo errore: dimenticare che in Pinia non esistono le mutations. Non cercare di chiamare store.$commit() — non esiste. Modifichi direttamente lo state. Questo è più semplice ma richiede una disciplina: le mutazioni non sono loggate automaticamente da DevTools? In realtà sì: Pinia traccia ogni modifica allo state, anche se fatta direttamente. Quindi hai lo stesso livello di debugging.

Terzo errore: creare troppi store quando basterebbe una sezione di un unico store. In Pinia ogni store è un modulo, ma non moltiplicare gli store senza criterio. Un negozio di e-commerce avrà uno store per carrello, uno per utente, uno per catalogo. Non serve uno store per ogni pagina.

Pinia vs Vuex — quale scegliere per un nuovo progetto Vue 3 nel 2026?

Non c'è partita. Per un nuovo progetto Vue 3, la scelta è Pinia. Vuex è in modalità manutenzione, non riceverà nuove feature. La documentazione ufficiale di Vue consiglia Pinia per tutti i nuovi progetti. Se hai un progetto esistente su Vuex, considera la migrazione: Pinia fornisce un bridge di compatibilità (vedi guida ufficiale di migrazione).

Noi, di Meteora Web, lo abbiamo fatto più volte. Il passaggio è indolore: spesso puoi mantenere la stessa struttura dello state, sostituendo le mutations con azioni e rimuovendo il namespacing. Il codice diventa più leggibile e il bundle più piccolo (Pinia pesa circa 1KB, Vuex 5KB).

Cosa fare adesso

1. Installa Pinia in un progetto Vue 3 esistente o nuovo: npm install pinia.
2. Crea il tuo primo store con defineStore e una funzione setup. Usa ref per lo state, computed per i getters, funzioni per le azioni.
3. Usa lo store in un componente con useXStore() e storeToRefs se necessario.
4. Aggiungi persistenza con pinia-plugin-persistedstate se hai dati da conservare (token, preferenze utente).
5. Leggi la documentazione ufficiale su pinia.vuejs.org — è chiara e ben strutturata.

Se hai un progetto Vuex esistente, valuta la migrazione. Se parti da zero, non guardare indietro. Pinia è lo strumento giusto per uno state management moderno, pulito e performante in Vue 3.