Stai iniziando un nuovo progetto Vue.js 3 e ti trovi di fronte a un bivio: scrivere componenti con la classica Options API o adottare la Composition API? Non sei il primo. Ogni settimana ci capita di discutere con clienti e team di sviluppo su quale strada prendere. La risposta giusta non è "sempre questa" o "mai quella": dipende dal contesto, dalla complessità e dal team. Noi, di Meteora Web, abbiamo costruito decine di applicazioni Vue — da piccoli widget a piattaforme complesse in Laravel + Vue — e abbiamo visto su pelle i vantaggi e i limiti di entrambe le API. In questa guida ti aiutiamo a scegliere con consapevolezza, senza fanatismi.
Capire le differenze fondamentali
Prima di decidere, devi capire cosa cambia davvero tra le due API. Non è solo sintassi: è un cambio di paradigma nel modo di organizzare la logica.
Options API: il classico che funziona
Se hai già usato Vue 2, conosci l'Options API. Definisci un componente come oggetto con proprietà specifiche: data, methods, computed, watch, mounted e via dicendo. Ogni opzione ha il suo posto fisso.
export default {
data() {
return {
count: 0,
step: 1
}
},
computed: {
double() {
return this.count * 2
}
},
methods: {
increment() {
this.count += this.step
}
}
}
È semplice, prevedibile, e chiunque abbia visto un componente Vue lo capisce subito. Il problema emerge quando il componente cresce. Logiche diverse (es. autenticazione, form validation, chiamate API) finiscono mescolate in mounted e methods, senza una chiara separazione. Lo abbiamo visto in progetti ereditati: un componente di 800 righe con data che conteneva flag di UI, stato utente e notifiche. Un disastro.
Composition API: organizzazione per funzionalità
La Composition API introduce la funzione setup e il concetto di composables. Non sei più vincolato a sezioni fisse: puoi raggruppare la logica per feature, estrarre funzioni riutilizzabili e avere un flusso più simile a JavaScript puro.
import { ref, computed } from 'vue'
export default {
setup() {
const count = ref(0)
const step = 1
const double = computed(() => count.value * 2)
function increment() {
count.value += step
}
return { count, double, increment }
}
}
Nota: count è un oggetto ref, perché Vue deve tracciare le reattività. Con reactive puoi usare oggetti più complessi. L'importante è che ora possiamo spostare queste funzioni in un file esterno, creando un composable.
// useCounter.js
import { ref, computed } from 'vue'
export function useCounter(initialStep = 1) {
const count = ref(0)
const step = initialStep
const double = computed(() => count.value * 2)
function increment() {
count.value += step
}
return { count, double, increment }
}
E nel componente:
import { useCounter } from './useCounter'
export default {
setup() {
const { count, double, increment } = useCounter(2)
return { count, double, increment }
}
}
Ora il componente è snello e la logica è testabile e riutilizzabile. Questo è il vero superpotere della Composition API.
Quando scegliere l'Options API
Non demonizziamo l'Options API. In molti scenari è ancora la scelta migliore:
- Componenti semplici e piccoli (es. un bottone, un input, un badge). Se hai poche righe di logica, l'Options API è più immediata e meno verbosa.
- Team con poca esperienza Vue o che provengono da Vue 2. La curva di apprendimento è più bassa e il codice è più autoesplicativo.
- Progetti piccoli o monouso (es. una landing page con un paio di componenti interattivi). L'overhead della Composition API non è giustificato.
- Quando usi librerie terze che si aspettano Options API (raro, ma possibile).
Noi stessi, in molti progetti interni o con clienti che richiedono manutenibilità immediata, usiamo l'Options API per il 70% dei componenti. La Composition API la riserviamo a logiche complesse o a componenti che devono essere riutilizzati in più contesti.
Quando passare alla Composition API
La Composition API brilla in questi casi:
- Componenti con logiche miste (es. un form che gestisce validazione, upload file, autocomplete). Con l'Options API finiresti con un groviglio; con la Composition API ogni feature può essere un composable separato.
- Riuso di logica tra componenti. Invece di mixin (problematici) o slot, usi composables. Ad esempio, un composable
useAuthper gestire login stato in tutta l'app. - Test unitari. I composables sono pure funzioni JavaScript, testabili senza montare componenti. Noi abbiamo ridotto il tempo di test del 40% passando a composables.
- Grandi applicazioni con decine di componenti. La Composition API permette di organizzare il codice per dominio, non per tipo di opzione.
- TypeScript. La Composition API è più facile da tipizzare (inferenza automatica con
refereactive).
Un esempio concreto: un cliente voleva un componente di dashboard con filtri, grafici e tabella. Con l'Options API avremmo avuto un mostro di 500 righe. Con la Composition API abbiamo creato useFilters, useChartData e useTableState. Ogni composable è stato testato isolatamente e riutilizzato in altre viste. Fatto.
Come migrare gradualmente (senza riscrivi tutto)
Non devi convertire ogni componente. Vue 3 supporta entrambe le API nello stesso progetto. Puoi iniziare a usare la Composition API per i nuovi componenti complessi e lasciare i vecchi in Options API. Nel tempo, quando tocchi un componente per bug o feature, lo puoi refactorizzare.
Ecco un esempio di migrazione di un componente con Options API che usa mounted per caricare dati:
// Options API
import axios from 'axios'
export default {
data() {
return { users: [], loading: false }
},
mounted() {
this.loadUsers()
},
methods: {
async loadUsers() {
this.loading = true
try {
const res = await axios.get('/api/users')
this.users = res.data
} finally {
this.loading = false
}
}
}
}
Versione con Composition API:
import { ref, onMounted } from 'vue'
import axios from 'axios'
export default {
setup() {
const users = ref([])
const loading = ref(false)
async function loadUsers() {
loading.value = true
try {
const res = await axios.get('/api/users')
users.value = res.data
} finally {
loading.value = false
}
}
onMounted(loadUsers)
return { users, loading }
}
}
Puoi anche estrarre la logica in un composable useUsers subito o dopo.
Errori comuni e best practices
Abbiamo visto alcuni errori frequenti quando si passa alla Composition API:
- Perdere la reattività: usare
const count = 0invece diref(0). Ricorda: Vue non traccia variabili normali. - Mischiare stili nello stesso file: evitare di avere metà componente in Options e metà in setup. Scegli una volta e sii coerente.
- Creare troppi ref per ogni proprietà: a volte un oggetto
reactiveè più pulito. Esempio:const state = reactive({ count: 0, step: 1 }). - Non gestire la cleanup: nei composable che usano
watchoonMounted, ricordati di fermare gli effetti cononUnmountedowatchEffectcon cleanup. - Over-engineering: non creare composable per ogni singola linea di logica. Se un componente ha 3 righe di setup, resta in Options API o in semplici ref.
Una best practice che seguiamo: inizia sempre con Options API, poi estrai in composable solo quando la logica cresce o si ripete. Così eviti astrazioni premature.
In sintesi — cosa fare adesso
- Valuta il tuo contesto: componente semplice? Team junior? Progetto piccolo? Usa Options API.
- Identifica logiche riutilizzabili: autenticazione, filtri, chiamate API comuni? Scrivi un composable con Composition API.
- Non riscrivere tutto: mescola le due API nello stesso progetto finché non è necessario refactorizzare.
- Testa i composable in isolamento: sono funzioni pure, approfittane.
- Documenta le scelte nel team: stabilisci una convenzione (es. “nuovi componenti con logica > 50 righe usano Composition API”).
Noi di Meteora Web usiamo questa regola pratica: l'Options API va forte per componenti di presentazione, la Composition API per logica di business. Se hai dubbi, parti dall'Options API e rifattorizza quando senti il puzzo di codice che si ripete. Come abbiamo visto anche per i React Hooks, la capacità di estrarre logica in funzioni autonome cambia la manutenibilità di un progetto. Scegli con testa, non con moda.
