Gatsby — Fondamenti · Marco Consiglio

🗺️ Cos'è Gatsby — siti statici costruiti con React

Gatsby è un Static Site Generator: prende contenuti (Markdown, dati da API, file locali) e componenti React, e genera in anticipo (al momento della "build") file HTML statici pronti per essere pubblicati — a differenza di un sito dinamico (come i progetti Laravel già visti) che genera l'HTML ad ogni richiesta, Gatsby lo genera UNA VOLTA, in anticipo.

Il risultato: pagine velocissime da caricare (sono file HTML già pronti, nessuna elaborazione server-side ad ogni visita) e più sicure (non c'è un database "vivo" da attaccare), al costo di dover "ricostruire" il sito quando il contenuto cambia.

🎯 Da dove si parte: serve conoscere Node.js di base (guida Node.js Fondamenti, in particolare npm) e avere familiarità con concetti di componenti/JSX di React (idealmente dopo la guida React Fondamenti) — questa guida introduce comunque Gatsby restando il più possibile autosufficiente.

⚙️ Creare il primo sito Gatsby

# installa il tool CLI di Gatsby globalmente (una sola volta) npm install -g gatsby-cli # crea un nuovo progetto da un template base gatsby new nome-progetto cd nome-progetto # avvia il server di sviluppo locale gatsby develop

💡 gatsby develop avvia un server locale su http://localhost:8000 CON ricaricamento automatico: modificando un file, il browser si aggiorna da solo — utile in sviluppo, ma il sito "vero" per la pubblicazione richiede il comando build (Passo 6).

📄 Pagine come file — routing automatico basato su cartelle

A differenza di Laravel/Express (dove le rotte si SCRIVONO esplicitamente, guide dedicate), in Gatsby OGNI file dentro src/pages/ diventa AUTOMATICAMENTE una pagina, con l'URL basato sul nome del file.

src/pages/ ├── index.js // diventa la homepage: / ├── chi-siamo.js // diventa: /chi-siamo └── contatti.js // diventa: /contatti

// src/pages/chi-siamo.js — un componente React è automaticamente una pagina import React from "react" export default function ChiSiamo() { return ( <main> <h1>Chi Siamo</h1> <p>Questa pagina è generata automaticamente da Gatsby.</p> </main> ) }

⚠️ Non serve ALCUNA configurazione di routing esplicita: aggiungere semplicemente un nuovo file src/pages/prezzi.js crea automaticamente la pagina /prezzi — un comportamento molto diverso dal routing esplicito già visto in Laravel (Route::get()) o Express (app.get()).

🔗 GraphQL — il "data layer" di Gatsby

Gatsby raccoglie TUTTI i dati del sito (contenuti Markdown, immagini, dati da API esterne) in un unico "magazzino" interrogabile con GraphQL, un linguaggio di interrogazione diverso da SQL (guide MySQL) ma con uno scopo simile: chiedere esattamente i dati che servono.

// esempio di query GraphQL eseguita dentro un componente di pagina import { graphql } from "gatsby" export const query = graphql\` query { site { siteMetadata { title } } } \` export default function Home({ data }) { return <h1>{data.site.siteMetadata.title}</h1> }

💡 A differenza di una query SQL (SELECT titolo FROM ..., guide MySQL) che si scrive dentro codice PHP eseguito lato server ad ogni richiesta, una query GraphQL in Gatsby viene eseguita durante la BUILD (Passo 6): il risultato è "congelato" nell'HTML statico generato, non ricalcolato ad ogni visita.

🔌 Plugin — estendere Gatsby senza scrivere tutto da zero

Come le librerie npm (guida Node.js Fondamenti), Gatsby ha un ecosistema di plugin che aggiungono funzionalità: leggere file Markdown, ottimizzare immagini, generare una sitemap.

// gatsby-config.js — dove si dichiarano i plugin attivi module.exports = { siteMetadata: { title: "Il mio sito Gatsby", }, plugins: [ "gatsby-plugin-image", // ottimizzazione automatica immagini "gatsby-transformer-remark", // trasforma file Markdown in dati interrogabili "gatsby-source-filesystem", // legge file dal file system come sorgente dati ], }

✅ L'ordine tipico: gatsby-source-filesystem LEGGE i file (es. articoli .md in una cartella), gatsby-transformer-remark li TRASFORMA in dati Markdown interrogabili via GraphQL — una pipeline dove ogni plugin aggiunge un pezzo alla catena di elaborazione dati.

🏗️ Build e deploy — generare i file statici finali

# genera i file HTML/CSS/JS statici finali, pronti per la pubblicazione gatsby build # la cartella 'public/' contiene ora il sito completo, pronto da caricare # su qualsiasi hosting statico (Netlify, Vercel, GitHub Pages, ecc.)

⚠️ gatsby develop (Passo 2) e gatsby build sono comandi DIVERSI con scopi diversi: develop è per lavorare e vedere le modifiche in tempo reale durante lo sviluppo; build genera la versione FINALE ottimizzata da pubblicare online — un principiante spesso confonde i due, provando a "pubblicare" l'output di develop, che non è pensato per la produzione.

🧩 Applicazioni tipiche

Tipologia	Uso tipico
Blog e siti di contenuti	Articoli scritti in Markdown, trasformati in pagine HTML statiche velocissime
Portfolio personali	Siti che cambiano raramente, dove la velocità di caricamento è prioritaria
Documentazione tecnica	Siti di documentazione con centinaia di pagine generate da file Markdown sorgente
NON adatto a	Applicazioni con dati che cambiano in tempo reale ad ogni richiesta (per quello, un'app dinamica come Laravel o React con API è più adatta)

🎓 Esercitazioni pratiche

Sito Gatsby con tre pagine

Crea un nuovo progetto Gatsby e aggiungi tre file in src/pages/ (index.js, chi-siamo.js, contatti.js), verificando che le rotte funzionino automaticamente senza configurazione esplicita.

⏱ 25 min📦 1 progetto Gatsby💻 Individuale

Query GraphQL del site title

Modifica gatsby-config.js impostando un title personalizzato in siteMetadata, poi scrivi una query GraphQL nella homepage che lo mostri in un tag h1.

⏱ 20 min📦 1 file modificato💻 Individuale

Build e ispezione della cartella public/

Esegui gatsby build sul progetto creato nell'esercitazione 1, poi apri la cartella public/ generata e verifica che contenga file .html corrispondenti a ciascuna pagina creata.

⏱ 15 min📦 Cartella public/💻 Individuale

Gatsby — Fondamenti per chi parte da zero

Report Quiz

🎓 Attestato di Competenze sbloccato!