Cursor non e' "VS Code con dentro ChatGPT". E' un editor che fa due cose nuove: capisce il TUO repository come un collega che lo conosce gia', e accetta task lunghi da delegare a un agente che lavora mentre tu fai altro. Imparare a usarlo bene cambia il modo di programmare. In questa guida costruiamo da zero una web app Next.js con autenticazione e database, partendo da una cartella vuota, fino al deploy in produzione su Vercel. Tutto guidato da Cursor.

Per chi e' questo tutorial

Per sviluppatori junior e mid-level che hanno usato VS Code e qualche chatbot, ma non hanno ancora un metodo per il "vibe coding" agentico. Anche per chi conosce gia' Cursor a livello base e vuole portare il flusso da "autocomplete intelligente" a "delego un task di 30 minuti e torno con la PR pronta".

Alla fine avrai una web app funzionante (lista task con login Google, persistenza su database, deploy live), e soprattutto avrai capito come strutturare il dialogo con Cursor per ottenere codice di qualita' e non spaghetti.

Prerequisiti reali

  • macOS, Windows o Linux (qualunque). 8 GB di RAM bastano, 16 sono comodi.
  • Node.js 20+ e Git installati. Verifica con node -v e git --version.
  • Un account GitHub e uno Vercel (gratis, basta accedere con GitHub).
  • Per il database useremo Supabase: account gratuito su supabase.com.
  • Per l'autenticazione Google ci serve un OAuth client ID da Google Cloud Console.

Quale piano Cursor scegliere

Cursor offre tre piani:

  • Hobby (gratis): 2 settimane di Pro in prova, poi 50 completamenti "Tab" rapidi al mese e accesso limitato all'agente. Sufficiente per testare ma non per un progetto reale.
  • Pro (20 dollari/mese): completamenti illimitati, ~500 richieste "fast" al mese ai modelli premium (Claude Opus 4.7, GPT-5.5, Gemini), agente Background con limiti generosi. E' il piano consigliato.
  • Ultra (40 dollari/mese): 4x quota Pro, agenti in parallelo, priorita' alta sui modelli premium.

Per questo tutorial il piano Pro e' piu' che sufficiente. Scarica Cursor da cursor.com, installa, fai login.

Le tre interazioni chiave (capirle e' il 60% del valore)

Cursor ti da' tre strumenti principali. Capire QUANDO usare QUALE e' la differenza fra usarlo bene e usarlo male:

  1. Tab (autocomplete predittivo): per piccole modifiche locali. Premi Tab e accetta la riga successiva proposta. Velocissimo.
  2. Chat (Cmd+L / Ctrl+L): per chiedere "spiegami questa funzione", "trova dove e' definita X", "scrivi un test per Y". Cursor pesca contesto dal repo automaticamente.
  3. Composer / Agent (Cmd+I / Ctrl+I): per task che toccano piu' file. "Aggiungi route /dashboard con questa struttura e i suoi componenti." Il modello pianifica, modifica i file, ti mostra il diff, applichi.

A questi si aggiunge il Background Agent (Cursor Pro+), che esegue task lunghi in cloud: lui clona il repo, scrive, lancia i test, apre la PR su GitHub. Lo useremo per il deploy.

Passo 1: setup del progetto

Apri Cursor e crea una cartella nuova todo-vibe. In terminale di Cursor (Ctrl+\` per aprirlo):

npx create-next-app@latest . --typescript --tailwind --app --no-src-dir --import-alias "@/*"
git init
git add . && git commit -m "init"

Apri Cmd+I per chiamare Composer e incolla:

Aggiungi al progetto Supabase per l'auth con Google e per salvare i task. Installa @supabase/supabase-js e @supabase/ssr. Crea un client server e un client browser, un middleware Next che protegge /app/dashboard, e una pagina /login con bottone "Continua con Google". Le credenziali leggile da .env.local (mettile come placeholder). Modello pulito, niente boilerplate inutile.

Cursor risponde con un piano (3-5 file) e i diff. Leggi: se la struttura ti convince clicca "Apply all". Altrimenti rifiuta un singolo file e chiedi una modifica.

Pro tip: chiedi sempre il piano prima del codice. Anziche' "aggiungi auth Supabase", scrivi "spiegami in 5 punti come integreresti Supabase auth con Google in Next 14 app router, poi aspetta conferma prima di modificare i file". Il piano cattura assunzioni che tu non avresti notato fino al merge.

Passo 2: configurazione Supabase e Google OAuth

Su supabase.com crea un progetto. Vai su Authentication {'>'} Providers {'>'} Google e attivalo: ti chiedera' un Client ID e Secret da Google Cloud Console (Console {'>'} APIs & Services {'>'} Credentials {'>'} Create OAuth client > Web application; come Redirect URI metti l'URL fornito da Supabase).

Copia URL e anon key di Supabase in un file .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOi...

Poi in Composer:

Crea nello Supabase project una tabella 'tasks' con colonne: id uuid primary key default gen_random_uuid(), user_id uuid not null references auth.users(id) on delete cascade, title text not null, done boolean default false, created_at timestamptz default now(). Aggiungi una policy RLS che permette SELECT/INSERT/UPDATE/DELETE solo all'utente con auth.uid() = user_id. Mostrami la query SQL pronta da incollare nell'editor SQL di Supabase.

Cursor genera lo statement SQL. Lo incolli nell'editor SQL di Supabase, esegui, fatto.

Passo 3: la pagina dashboard con i task

Adesso il pezzo grosso. Apri Composer:

In /app/dashboard/page.tsx crea una pagina server-component che: 1) controlla la sessione, redirect a /login se mancante; 2) carica i task dell'utente da Supabase; 3) renderizza una lista. Sotto la lista metti un form (client component) per aggiungere un task, un toggle per marcarli done, e un bottone elimina. Usa Tailwind, design minimale ma curato (border, padding generosi, font medium). Niente CSS inline. Crea i componenti necessari come file separati in /app/dashboard/_components.

Cursor crea 4-5 file e li mostra in diff. Applica, lancia npm run dev, apri localhost:3000. Fai login con Google, aggiungi un task, controlla che persista.

Se qualcosa non funziona, NON correggere a mano: torna in Composer e descrivi il problema. "Cliccando 'aggiungi task' non succede nulla; in console vedo: 'PGRST301: violates row-level security'. Spiegami la causa e applica la fix." Cursor ti dira' che il client non passa la sessione e patchera' il createClient.

Passo 4: test, refactor e Background Agent

Per la qualita', chiedi a Cursor:

Aggiungi test con Vitest per le funzioni di accesso dati (CRUD tasks). Mocka il client Supabase. Aggiungi anche un GitHub Action che lancia npm test su ogni PR.

Per un refactor profondo - per esempio "sposta tutta la logica di Supabase in /lib/supabase/queries.ts e usa hook React Query" - apri il Background Agent: Cmd+Shift+I, scrivi il task, lui clona il repo nel cloud, esegue, ti torna una PR su GitHub gia' aperta con i test passati. Tu vai a fare un caffe' e ricontrolli.

Passo 5: deploy su Vercel

Spingi il repo su GitHub. Vai su Vercel, importalo. Aggiungi le environment variables (le stesse del .env.local, ovviamente con i valori reali). Clicca Deploy. In 90 secondi hai la URL pubblica.

Aggiorna il Redirect URI di Google OAuth e di Supabase con la URL Vercel. Riprova il login. Fatto.

I cinque errori che fa quasi tutti i principianti

  • Dare contesto vago. "Sistema il login" non basta. "Quando l'utente non e' loggato, /dashboard mostra un flash di contenuto prima del redirect. Sistemare con il middleware o con redirect lato server." Specifico, replicabile.
  • Accettare il primo diff senza leggerlo. Cursor a volte aggiunge dipendenze nuove o cambia file che non doveva toccare. Leggi sempre la lista dei file modificati.
  • Non usare i commit Git come checkpoint. Committa dopo ogni feature funzionante. Se il prossimo task va male, git reset --hard e' la tua rete.
  • Usare Tab per cose grandi. Tab e' per il completion locale. Per modifiche multi-file, sempre Composer.
  • Non sfruttare @-mention. In chat o in Composer, scrivi @File, @Folder, @Doc per puntare l'attenzione del modello esattamente al pezzo che ti serve. Risposte molto migliori.

Quando NON usare Cursor

Tre casi:

  • Codice altamente regolamentato (sanita', difesa, finanza con dati on-prem): senza una versione enterprise self-hosted, i prompt e parti di codice transitano dai server Anysphere e Anthropic/OpenAI.
  • Refactor enormi su monorepo legacy: il modello fatica a tenere il contesto, anche con 1M token. JetBrains AI Assistant dentro un IntelliJ con indici nativi e' spesso piu' bravo.
  • Quando devi DAVVERO imparare: se sei agli inizi, fare tutto delegando a Cursor ti dara' un'illusione di competenza. Alterna sessioni "con Cursor" a sessioni "senza".

Come continuare

Cursor ha tre risorse ufficiali che valgono il bookmark: la documentazione, i Rules per impostare convenzioni di progetto (.cursor/rules), e gli MCP server (Model Context Protocol) che permettono di dare all'agente accesso ai tuoi tool: GitHub, Linear, database, browser. Una volta che hai capito Composer e Background Agent, gli MCP sono il passo successivo: trasformano Cursor da editor potenziato a piattaforma di agenti che lavora per te.

Per misurare il salto: misura il tempo che oggi impieghi su un task tipico - una nuova route, un refactor, un fix - e quanto ci impieghi fra una settimana. Per molti sviluppatori la riduzione e' del 40-60%. Per altri (che si fidano troppo del primo output), il codice peggiora prima di migliorare. La differenza, banalmente, sta nel come gli si parla.