Installazione e Setup

Creare un Progetto con SvelteKit

SvelteKit è il modo raccomandato per iniziare un nuovo progetto Svelte. Utilizza Vite come bundler e offre SSR, routing file-based e molto altro.

Comando di creazione

# Crea un nuovo progetto SvelteKit
npx sv create my-app

# Entra nella cartella del progetto
cd my-app

# Installa le dipendenze
npm install

# Avvia il dev server
npm run dev

Durante la creazione, il CLI ti chiederà di scegliere:

Template: Skeleton project (vuoto), Demo app o Library
Type checking: TypeScript (consigliato), JSDoc o nessuno
Add-ons: ESLint, Prettier, Vitest, Playwright, ecc.

Opzioni consigliate per un nuovo progetto

npx sv create my-app
# ✔ Template: Skeleton project
# ✔ Type checking: TypeScript
# ✔ Add-ons: prettier, eslint, vitest, playwright

Creare un Progetto con Vite (senza SvelteKit)

Se non hai bisogno di SSR, routing file-based o le funzionalità server di SvelteKit, puoi creare un progetto Svelte puro con Vite.

# Con npm
npm create vite@latest my-app -- --template svelte

# Con TypeScript
npm create vite@latest my-app -- --template svelte-ts

cd my-app
npm install
npm run dev

Questa opzione è ideale per:

Widget embeddabili in altre applicazioni
SPA pure senza necessità di SSR
Prototipi rapidi senza overhead di SvelteKit
Micro-frontend o componenti standalone

Struttura delle Cartelle

Progetto SvelteKit

my-app/
├── src/
│   ├── lib/                    # Libreria condivisa ($lib alias)
│   │   ├── components/         # Componenti riutilizzabili
│   │   │   ├── Header.svelte
│   │   │   └── Footer.svelte
│   │   ├── stores/             # Store globali
│   │   │   └── auth.ts
│   │   ├── utils/              # Funzioni di utilità
│   │   │   └── format.ts
│   │   └── index.ts            # Esportazioni principali
│   ├── routes/                 # Route dell'applicazione
│   │   ├── +page.svelte        # Home page (/)
│   │   ├── +page.ts            # Load function per home
│   │   ├── +layout.svelte      # Layout principale
│   │   ├── +error.svelte       # Pagina errore globale
│   │   ├── about/
│   │   │   └── +page.svelte    # Pagina /about
│   │   └── blog/
│   │       ├── +page.svelte    # Lista blog /blog
│   │       └── [slug]/
│   │           └── +page.svelte # Singolo post /blog/:slug
│   ├── app.html                # Template HTML principale
│   ├── app.css                 # Stili globali
│   └── app.d.ts                # Tipi globali
├── static/                     # Asset statici (favicon, immagini)
│   └── favicon.png
├── tests/                      # Test end-to-end
├── svelte.config.js            # Configurazione Svelte
├── vite.config.ts              # Configurazione Vite
├── tsconfig.json               # Configurazione TypeScript
└── package.json

Progetto Vite (senza SvelteKit)

my-app/
├── src/
│   ├── lib/                    # Componenti e utilità
│   │   └── Counter.svelte
│   ├── App.svelte              # Componente root
│   ├── main.ts                 # Entry point
│   └── vite-env.d.ts           # Tipi Vite
├── public/                     # Asset statici
├── index.html                  # HTML entry point
├── vite.config.ts
├── tsconfig.json
└── package.json

File di Configurazione

svelte.config.js

Il file di configurazione principale per SvelteKit:

import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Preprocessori (necessario per TypeScript, SCSS, ecc.)
  preprocess: vitePreprocess(),

  kit: {
    // Adapter per il deployment
    adapter: adapter(),

    // Personalizzazione alias
    alias: {
      '$components': 'src/lib/components',
      '$stores': 'src/lib/stores',
      '$utils': 'src/lib/utils'
    }
  }
};

export default config;

vite.config.ts

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [sveltekit()],
  test: {
    include: ['src/**/*.{test,spec}.{js,ts}']
  },
  server: {
    port: 5173,
    open: true  // Apre il browser automaticamente
  }
});

tsconfig.json

{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strict": true,
    "moduleResolution": "bundler"
  }
}

Il Dev Server

Avvio e comandi

# Avvia il server di sviluppo
npm run dev

# Avvia con network access (per testare da altri dispositivi)
npm run dev -- --host

# Avvia su una porta specifica
npm run dev -- --port 3000

# Build per produzione
npm run build

# Preview della build di produzione
npm run preview

Hot Module Replacement (HMR)

Vite offre HMR istantaneo: quando modifichi un file .svelte, il browser si aggiorna quasi istantaneamente senza ricaricare la pagina. Lo stato dei componenti viene preservato quando possibile.

Il File app.html

Il template HTML principale in SvelteKit:

<!DOCTYPE html>
<html lang="it">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%sveltekit.assets%/favicon.png" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    %sveltekit.head%
  </head>
  <body data-sveltekit-preload-data="hover">
    <div style="display: contents">%sveltekit.body%</div>
  </body>
</html>

I placeholder %sveltekit.head% e %sveltekit.body% vengono sostituiti dal contenuto generato da SvelteKit durante il rendering.

Adapter per il Deployment

SvelteKit utilizza gli adapter per generare output specifici per diverse piattaforme:

# Adapter per Node.js
npm install @sveltejs/adapter-node

# Adapter per siti statici
npm install @sveltejs/adapter-static

# Adapter per Vercel
npm install @sveltejs/adapter-vercel

# Adapter per Netlify
npm install @sveltejs/adapter-netlify

# Adapter per Cloudflare
npm install @sveltejs/adapter-cloudflare

Configurazione dell’adapter nel svelte.config.js:

// Per generare un sito statico
import adapter from '@sveltejs/adapter-static';

const config = {
  kit: {
    adapter: adapter({
      pages: 'build',
      assets: 'build',
      fallback: '404.html',
      precompress: true
    })
  }
};

export default config;

L’Alias $lib

SvelteKit configura automaticamente l’alias $lib che punta a src/lib/. Questo evita import relativi complessi:

<script>
  // Invece di questo (fragile e brutto)
  import Header from '../../../lib/components/Header.svelte';

  // Usa l'alias $lib
  import Header from '$lib/components/Header.svelte';
</script>

Primo Componente

Dopo aver creato il progetto, modifica src/routes/+page.svelte:

<script>
  let nome = $state('Mondo');
  let contatore = $state(0);
</script>

<main>
  <h1>Ciao, {nome}!</h1>

  <input bind:value={nome} placeholder="Il tuo nome" />

  <button onclick={() => contatore++}>
    Contatore: {contatore}
  </button>
</main>

<style>
  main {
    max-width: 600px;
    margin: 0 auto;
    padding: 2rem;
    text-align: center;
  }

  input {
    padding: 0.5rem;
    font-size: 1rem;
    border: 1px solid #ccc;
    border-radius: 4px;
  }

  button {
    padding: 0.5rem 1rem;
    font-size: 1rem;
    background: #ff3e00;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  }

  button:hover {
    background: #e63600;
  }
</style>

Best Practice per la Struttura del Progetto

Usa $lib per tutto il codice condiviso tra le route
Organizza per feature: raggruppa componenti, store e utilità correlati
Separa componenti di UI e componenti di pagina: i componenti in $lib dovrebbero essere generici
Usa TypeScript: aiuta enormemente la manutenzione a lungo termine
Configura ESLint e Prettier fin dall’inizio per mantenere il codice consistente
Usa index.ts barrel exports in $lib per semplificare gli import