Installare Svelte 5 con Vite e TypeScript e creare la prima applicazione

Dopo aver lavorato con Node.js, Express, TypeScript e MongoDB, è il momento di passare al frontend. Finora abbiamo costruito la parte server di un'applicazione web, cioè quella che gestisce le API, le richieste HTTP e l'accesso al database. Adesso realizzeremo l'interfaccia che permette agli utenti di interagire con queste funzionalità attraverso il browser.

In questa serie utilizzerò Svelte 5, un framework JavaScript per costruire interfacce web, insieme a TypeScript. L'obiettivo non sarà soltanto creare una pagina che visualizza del testo, ma capire come viene organizzato un progetto, come si avvia un ambiente di sviluppo e come si scrive un componente Svelte.

Per iniziare utilizzerò Vite, uno strumento che crea e gestisce l'ambiente di sviluppo frontend. Vite offre un server di sviluppo rapido e prepara il progetto per la compilazione destinata alla produzione. Non è un'alternativa a Svelte: i due strumenti hanno responsabilità diverse e lavorano insieme.

In questo primo tutorial installerò le dipendenze, analizzerò la struttura del progetto e modificherò il componente principale per realizzare una piccola applicazione interattiva. Alla fine saprò avviare il progetto, riconoscere i file principali e comprendere il funzionamento di un componente Svelte 5. Queste basi saranno necessarie per affrontare reattività, props, form e chiamate HTTP nei prossimi tutorial.

Che cos'è Svelte

Svelte è un framework per costruire interfacce utente attraverso componenti. Un componente può contenere markup, logica JavaScript o TypeScript e stili CSS. Questa organizzazione permette di suddividere una pagina complessa in elementi più piccoli e riutilizzabili.

A differenza di un approccio basato esclusivamente su manipolazioni manuali del DOM, Svelte permette di descrivere come deve apparire l'interfaccia a partire dallo stato dell'applicazione. Quando lo stato cambia, il framework aggiorna le parti interessate dell'interfaccia. Non dobbiamo quindi cercare manualmente ogni elemento HTML e modificarlo ogni volta che cambia un dato.

Svelte 5 introduce un sistema di reattività chiamato Runes. Tra le principali ci sono $state, per dichiarare stato reattivo, $derived, per calcolare valori derivati e $effect, per gestire effetti collaterali. Le vedremo nel dettaglio nel prossimo tutorial. Per il momento è sufficiente sapere che sono parte della sintassi moderna di Svelte 5.

Svelte, inoltre, non obbliga a utilizzare un framework full-stack per ogni progetto. Possiamo costruire una semplice applicazione frontend e collegarla a un backend già esistente. È esattamente l'approccio che adotteremo prima di introdurre SvelteKit.

Che cos'è Vite e perché lo utilizziamo

Vite è uno strumento per lo sviluppo frontend. Si occupa di avviare il server di sviluppo, elaborare i moduli dell'applicazione e fornire gli strumenti necessari per costruire una versione pronta per la pubblicazione.

Durante lo sviluppo, Vite aggiorna rapidamente il browser quando modifichiamo i file. Questo comportamento è particolarmente utile quando lavoriamo sui componenti e vogliamo vedere subito il risultato delle modifiche.

È importante distinguere i ruoli: Svelte è il framework con cui scriviamo i componenti, mentre Vite gestisce l'ambiente di sviluppo e la build. In un secondo momento potremo introdurre SvelteKit, che aggiunge funzionalità come routing basato sui file, caricamento dei dati e rendering server-side.

Verificare l'ambiente di sviluppo

Prima di creare il progetto, verifico che Node.js e npm siano disponibili. Sul mio ambiente Fedora apro il terminale ed eseguo:

node --version
npm --version

Il primo comando visualizza la versione di Node.js, mentre il secondo mostra quella di npm, il gestore dei pacchetti JavaScript. Nel mio ambiente di studio Node.js è già installato, quindi non devo ripetere l'installazione.

Non è necessario utilizzare esattamente le stesse versioni riportate negli esempi di un tutorial. È però opportuno utilizzare una versione di Node.js supportata dalle versioni correnti degli strumenti scelti e mantenere coerenti le dipendenze del progetto.

Se uno dei due comandi restituisce un errore, devo risolvere prima la configurazione di Node.js e npm. In caso contrario posso procedere direttamente alla creazione dell'applicazione.

Creare il progetto Svelte con Vite

Creo una directory dedicata ai progetti frontend, separata da quella in cui si trova il backend Express:

cd ~/dev
npm create vite@latest svelte-study -- --template svelte-ts

Il comando utilizza npm create vite@latest per avviare lo strumento di creazione del progetto Vite. Il nome svelte-study identifica la directory che verrà creata, mentre --template svelte-ts seleziona il modello ufficiale basato su Svelte e TypeScript.

Il parametro -- separa gli argomenti destinati a npm da quelli passati al programma Vite. In questo caso consente di trasmettere correttamente il nome del template.

Se lo strumento pone domande aggiuntive, seguo le opzioni coerenti con il template Svelte e TypeScript. Evito di aggiungere librerie non necessarie: per il primo esercizio voglio un progetto essenziale, così ogni file avrà una funzione comprensibile.

Una volta terminata la creazione, entro nella directory del progetto:

cd svelte-study

È importante eseguire i comandi successivi da questa directory, perché è qui che si trova il file package.json con la configurazione e le dipendenze dell'applicazione.

Installare le dipendenze

Il progetto generato contiene la configurazione necessaria, ma devo ancora installare i pacchetti richiesti. Eseguo:

npm install

npm legge package.json e installa le dipendenze dichiarate, creando la directory node_modules e aggiornando o generando il file package-lock.json.

Il file package.json contiene i metadati del progetto, gli script disponibili e le dipendenze dichiarate. Il file package-lock.json, invece, registra le versioni effettivamente risolte delle dipendenze, contribuendo a rendere più riproducibili le installazioni.

La directory node_modules contiene i pacchetti installati e non deve essere inserita nel repository Git. Normalmente è sufficiente escluderla tramite .gitignore, come avviene nel template creato da Vite.

Avviare il server di sviluppo

Dopo l'installazione avvio il progetto:

npm run dev

Il comando esegue lo script dev definito in package.json. Vite avvia il server di sviluppo e mostra nel terminale un indirizzo locale, normalmente http://localhost:5173.

Apro l'indirizzo indicato nel browser. Se tutto è configurato correttamente, visualizzo la pagina iniziale del template Svelte.

Il server rimane attivo finché non lo interrompo con Ctrl+C nel terminale. Quando modifico i file del progetto, Vite aggiorna la pagina automaticamente nella maggior parte dei casi, senza dover interrompere e riavviare il server.

Questa modalità è pensata per lo sviluppo. Non equivale alla pubblicazione di un'applicazione in produzione, per la quale utilizzeremo il comando di build.

Analizzare la struttura del progetto

Il template Svelte con TypeScript crea diversi file e directory. La struttura può variare leggermente tra le versioni del template, ma gli elementi principali sono simili a questi:

svelte-study/
├── node_modules/
├── public/
├── src/
│   ├── lib/
│   ├── App.svelte
│   ├── app.css
│   └── main.ts
├── index.html
├── package.json
├── package-lock.json
├── tsconfig.json
└── vite.config.ts

La directory src contiene il codice sorgente dell'applicazione. Il file App.svelte rappresenta il componente principale, mentre main.ts è il punto di ingresso TypeScript dal quale viene inizializzata l'applicazione.

Il file app.css contiene gli stili globali iniziali. La directory public è destinata agli asset statici serviti direttamente, come immagini o file che non devono essere elaborati come moduli del codice.

index.html è la pagina HTML iniziale nella quale viene montata l'applicazione. vite.config.ts contiene la configurazione di Vite, mentre tsconfig.json definisce le impostazioni di TypeScript. Infine, package.json raccoglie le dipendenze e gli script utilizzabili da terminale.

Non è necessario conoscere subito ogni dettaglio. Per iniziare ci concentreremo soprattutto su App.svelte, mantenendo intatti i file di configurazione generati dal template.

Capire un componente Svelte

I componenti Svelte utilizzano l'estensione .svelte. Un componente può contenere tre parti principali: un blocco di script, il markup HTML e un blocco di stili.

Il blocco script contiene la logica scritta in TypeScript. Il markup descrive gli elementi che devono apparire nella pagina, mentre il blocco style contiene gli stili CSS associati al componente.

Non è obbligatorio che tutte e tre le parti siano presenti. Un componente che visualizza soltanto del testo potrebbe non aver bisogno di uno script, mentre un componente dedicato alla logica potrebbe avere un markup molto semplice.

Questa struttura rende i componenti relativamente facili da leggere: il codice che gestisce un elemento dell'interfaccia si trova vicino al markup e agli stili che lo riguardano. Nei progetti più grandi potremo distribuire le responsabilità in più componenti, evitando di concentrare tutto in un unico file.

Realizzare la prima applicazione interattiva

Ora sostituisco il contenuto di src/App.svelte con un esempio semplice. L'applicazione visualizzerà un contatore e due pulsanti per incrementare e decrementare il valore.

<script lang="ts">
  let count = $state(0);
</script>

<svelte:head>
  <title>Il mio primo progetto Svelte</title>
  <meta
    name="description"
    content="La mia prima applicazione realizzata con Svelte 5 e TypeScript"
  />
</svelte:head>

<main>
  <h1>Il mio primo progetto Svelte</h1>

  <p>
    Ho creato la mia prima applicazione con Svelte 5 e TypeScript.
  </p>

  <section aria-labelledby="counter-title">
    <h2 id="counter-title">Contatore</h2>

    <p class="counter-value">Valore attuale: {count}</p>

    <div class="actions">
      <button onclick={() => count--}>
        Decrementa
      </button>

      <button onclick={() => count++}>
        Incrementa
      </button>
    </div>

    <button class="reset" onclick={() => count = 0}>
      Azzera
    </button>
  </section>
</main>

<style>
  main {
    max-width: 680px;
    margin: 4rem auto;
    padding: 0 1.5rem;
    font-family: system-ui, sans-serif;
  }

  h1 {
    margin-bottom: 0.75rem;
  }

  section {
    margin-top: 2rem;
    padding: 1.5rem;
    border: 1px solid #d1d5db;
    border-radius: 12px;
  }

  .counter-value {
    font-size: 1.25rem;
    font-weight: 600;
  }

  .actions {
    display: flex;
    gap: 0.75rem;
    flex-wrap: wrap;
  }

  button {
    padding: 0.65rem 1rem;
    border: 0;
    border-radius: 6px;
    cursor: pointer;
    font: inherit;
  }

  .reset {
    margin-top: 0.75rem;
  }
</style>

Salvo il file e torno nel browser. Dovrei vedere il titolo, il valore iniziale del contatore e i tre pulsanti. Cliccando su Incrementa il valore aumenta, cliccando su Decrementa diminuisce e cliccando su Azzera torna a zero.

Questo piccolo esempio introduce tre concetti fondamentali di Svelte 5: lo stato reattivo, l'interpolazione dei valori nel markup e la gestione degli eventi. Nel prossimo tutorial li analizzeremo separatamente, per capire perché il browser aggiorna il contatore senza che io debba manipolare direttamente il DOM.

Capire il ruolo di $state

Nel codice ho dichiarato la variabile count in questo modo:

let count = $state(0);

$state è una Rune di Svelte 5. Serve a dichiarare uno stato reattivo: quando il valore cambia, Svelte rileva la modifica e aggiorna le parti dell'interfaccia che dipendono da quel valore.

Se avessi dichiarato semplicemente let count = 0, non avrei ottenuto lo stesso comportamento reattivo con questa sintassi moderna. $state comunica esplicitamente a Svelte che il valore deve partecipare al sistema di reattività.

Quando scrivo {count} nel markup, sto interpolando il valore della variabile. Svelte visualizza il numero corrente e aggiorna il testo quando lo stato cambia. Non devo richiamare manualmente una funzione per aggiornare il contenuto di un elemento HTML.

Per il momento mi basta capire questo meccanismo. Nel prossimo tutorial vedremo anche $derived, utile per calcolare valori a partire da altri stati, e analizzeremo meglio quando utilizzare le diverse Runes.

Capire gli eventi e gli stili

I pulsanti utilizzano la sintassi onclick, per esempio:

<button onclick={() => count++}>
  Incrementa
</button>

Quando l'utente fa clic, viene eseguita la funzione indicata e il contatore aumenta. La sintassi con onclick è quella moderna di Svelte 5 per gli eventi DOM. Negli esempi più vecchi potresti trovare on:click, ma in questo tutorial utilizzeremo la sintassi moderna.

Il blocco contiene gli stili del componente. Svelte applica normalmente uno scope agli stili dei componenti, evitando che ogni regola CSS finisca automaticamente per influenzare tutti gli elementi dell'intera applicazione.

Ho inoltre utilizzato elementi HTML semantici, come main, section e i titoli. Non è soltanto una questione estetica: una struttura comprensibile aiuta l'accessibilità e rende più semplice mantenere il codice.

Verificare TypeScript e preparare la build

Dopo aver verificato il funzionamento dell'applicazione, posso controllare la configurazione TypeScript e la build.

Il template Vite generato include normalmente uno script per la build e uno per il controllo dei tipi. Verifico gli script disponibili in package.json e lancio quelli effettivamente presenti. In un template recente, i comandi possono essere:

npm run check npm run build

Il comando check esegue il controllo statico previsto dal template Svelte. Il comando build crea invece una versione ottimizzata dell'applicazione per la distribuzione.

Se il comando check non è presente negli script del progetto generato, controllo package.json anziché inventare uno script. I template possono cambiare tra versioni, quindi è sempre la configurazione reale del progetto a stabilire quali comandi siano disponibili.

La build non sostituisce i test funzionali: una compilazione riuscita dimostra che il progetto ha superato i controlli previsti, ma non garantisce che ogni interazione sia corretta. Per questo ho verificato anche il contatore direttamente nel browser.

Conclusione

In questo tutorial ho creato un progetto Svelte 5 con Vite e TypeScript, installato le dipendenze, avviato il server di sviluppo e analizzato i principali file generati. Ho inoltre realizzato un primo componente interattivo utilizzando $state, interpolazione e gestione degli eventi.

La cosa importante non è il contatore in sé, ma il modello di lavoro: dichiaro lo stato, descrivo come deve essere rappresentato nell'interfaccia e lascio che Svelte gestisca gli aggiornamenti necessari. È questo approccio che renderà più semplice costruire componenti complessi nei prossimi passaggi.

Nel Tutorial 2 approfondirò il sistema di reattività di Svelte 5, partendo da $state e introducendo $derived e $effect. Una volta capiti questi concetti, potrò affrontare componenti con props, form e chiamate HTTP prima di passare a SvelteKit.