Cloudflare Pages: deployare un sito statico in pochi minuti

Cloudflare Pages è la piattaforma JAMstack di Cloudflare per ospitare gratuitamente siti statici e SPA con build automatica da repository Git. Compete direttamente con Vercel e Netlify offrendo bandwidth illimitato anche sul piano Free, deploy in pochi secondi tramite la rete edge globale e integrazione nativa con Workers per logica server-side. È la scelta ideale per landing page, portfolio, blog statici e applicazioni React, Vue, Svelte, Astro.

Architettura di Pages

Pages connette un repository GitHub o GitLab al tuo account Cloudflare. A ogni push viene eseguita la build configurata (npm run build, hugo, jekyll, etc.) e il risultato viene distribuito globalmente sui POP edge. Ogni branch riceve un'anteprima preview con URL unico, perfetta per pull request review. Il dominio di produzione (custom domain) è facilmente collegabile e include SSL gratuito.

Procedura passo-passo

1. Vai sul dashboard Cloudflare → Workers & Pages.
2. Clicca Create application → Pages → Connect to Git.
3. Autorizza Cloudflare ad accedere a GitHub o GitLab.
4. Seleziona il repository da deployare.
5. Configura il framework preset (Next.js, Astro, Hugo, etc.) o lascia None.
6. Imposta il comando di build (es. npm run build) e directory output (es. dist o .next).
7. Aggiungi variabili d'ambiente se necessarie (API keys, NODE_VERSION).
8. Avvia il primo deploy e attendi 1-3 minuti.
9. Vai su Custom domains e aggiungi tuosito.it.
10. Cloudflare configura automaticamente i record DNS e SSL.

Framework supportati

Cloudflare Pages supporta nativamente: Next.js (con Edge runtime), Nuxt 3, Astro, SvelteKit, Remix, Gatsby, Hugo, Jekyll, Eleventy, Vite, Vue CLI, Create React App, Angular CLI, Docusaurus. Il preset configura automaticamente comando build e directory output. Per progetti custom puoi configurare tutto manualmente. La build avviene su container Linux con Node 18 di default (modificabile via NODE_VERSION).

Functions: Workers integrati

Pages supporta nativamente Functions, ovvero file JavaScript/TypeScript nella cartella /functions che diventano endpoint serverless eseguiti come Workers. Esempio: functions/api/hello.ts diventa accessibile a tuosito.it/api/hello. Le Functions hanno accesso a tutte le risorse Workers (KV, R2, D1, Durable Objects) e permettono di costruire API full-stack senza gestire infrastruttura.

Preview deployments

Ogni branch non production riceve un'URL preview del tipo branchname.miosito.pages.dev. Le pull request hanno commenti automatici con link al preview, ideali per review prima del merge. La preview è isolata e usa variabili d'ambiente separate dalla produzione, quindi puoi puntare a database staging. Una volta mergiato il branch in main, il deploy production parte automaticamente.

Errori comuni e come risolverli

• Build fallisce: command not found: aggiungi NODE_VERSION nelle env e verifica package.json.
• 404 dopo deploy: directory output sbagliata. Verifica nel framework il path corretto (dist, build, .next, public).
• Asset non trovati: base URL relativa errata. Configura publicPath o base nel build tool.
• Custom domain bloccato in pending: il dominio non è ancora su Cloudflare. Migra prima i nameserver.
• Build time too long: il piano Free ha 20 minuti max. Ottimizza la build o passa a Pages Paid.

Limiti del piano Free

Cloudflare Pages Free offre: 500 build/mese, 100 custom domains, bandwidth illimitato, deploy illimitati, 20 minuti max per build, 25MB max per file, 20.000 file max per progetto. La maggior parte degli sviluppatori non raggiunge mai questi limiti. Per agency con molti progetti o build più lunghe esiste il piano Pages Paid a 20 dollari/mese con limiti molto più alti.

Domande frequenti

D: Posso usare Pages per WordPress?
R: No, WordPress è dinamico (PHP+MySQL). Pages è per siti statici o SPA.

D: Devo avere il dominio già su Cloudflare?
R: Non necessariamente. Puoi usare il sottodominio pages.dev gratuito, ma per custom domain il DNS deve essere su Cloudflare.

D: Quanto è veloce il deploy?
R: La distribuzione globale è quasi istantanea (sotto i 30 secondi) dopo la build.

D: Posso rollback a una versione precedente?
R: Sì, dal dashboard ogni deploy passato resta accessibile e ripristinabile in un clic.

Considerazioni operative finali

Quando applichi una configurazione di questo tipo in produzione è sempre buona norma seguire un'approccio incrementale: parti con un test su staging, monitora gli effetti per qualche giorno, poi estendi gradualmente al traffico live. La rete Cloudflare elabora ogni cambiamento in pochi secondi a livello globale, quindi le modifiche sono effettive quasi immediatamente, ma gli effetti collaterali su utenti reali possono richiedere ore o giorni per emergere. Annota nel runbook interno data, motivo e parametri di ogni modifica significativa. Una documentazione precisa accelera enormemente il troubleshooting futuro e facilita il passaggio di consegne tra membri del team.

Vale anche la pena ricordare che Cloudflare aggiorna frequentemente l'interfaccia del dashboard e le posizioni delle voci di menu. La logica e le funzionalità descritte in questa guida restano valide, ma il percorso esatto per raggiungere ogni opzione può variare leggermente nel tempo. In caso di difficoltà a trovare una specifica voce, utilizza la barra di ricerca interna del dashboard oppure consulta la documentazione ufficiale aggiornata. La community Cloudflare sul forum ufficiale e su Stack Overflow è inoltre molto attiva e offre spesso risposte rapide a problemi specifici di configurazione.

Per progetti complessi che coinvolgono più servizi Cloudflare contemporaneamente (CDN, Workers, WAF, Access, R2) conviene strutturare la configurazione come codice tramite Terraform o Pulumi. Questo permette versioning, code review, rollback atomici e deploy ripetibili tra environment. Per team con esigenze più semplici la gestione manuale via dashboard resta perfettamente valida, soprattutto se accompagnata da una checklist scritta delle impostazioni applicate. La scelta dell'approccio dipende dalle dimensioni del progetto e dal grado di automazione desiderato. L'importante è essere consistenti e mantenere tracciabilità delle modifiche effettuate.

Hai bisogno di aiuto?

Se vuoi configurare Cloudflare per il tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.