Salta ai contenuti

Effettua il deploy del tuo sito Astro su Cloudflare Pages

Puoi effettuare il deploy del tuo progetto Astro su Cloudflare Pages, una piattaforma per sviluppatori frontend che consente di collaborare e pubblicare siti web statici (JAMstack) e SSR.

Questa guida include:

Per iniziare, avrai bisogno di:

  • Un account su Cloudflare. Se non ne hai già uno, puoi crearne uno gratuitamente durante il processo.
  • Il codice della tua app caricato su un repository GitHub o GitLab.

Come effettuare il deploy di un sito utilizzando Git

Sezione intitolata Come effettuare il deploy di un sito utilizzando Git
  1. Configura un nuovo progetto su Cloudflare Pages.

  2. Esegui il push del tuo codice nel tuo repository Git (GitHub, GitLab).

  3. Accedi al pannello di controllo di Cloudflare e seleziona il tuo account in Account Home > Pages.

  4. Clicca su Crea applicazione e dopo sull’opzione Esegui la connessione a Git.

  5. Seleziona il progetto git che desideri pubblicare e clicca su Inizia configurazione.

  6. Utilizza le seguenti impostazioni per la build:

    • Framework preimpostato: Astro
    • Comando di build: npm run build
    • Directory di output della build: dist
  7. Clicca il pulsante Salva e Distribuisci.

Come effettuare il deploy di un sito utilizzando Wrangler

Sezione intitolata Come effettuare il deploy di un sito utilizzando Wrangler
  1. Installa Wrangler.
  2. Esegui il login con il tuo account Cloudflare utilizzando il comando wrangler login.
  3. Esegui il comando per avviare la build.
  4. Effettua il deploy utilizzando il comando npx wrangler pages publish dist.
Terminal window
# Installa Wrangler CLI
npm install -g wrangler
# Accedi all'account Cloudflare da CLI
wrangler login
# Esegui il comando di build
npm run build
# Crea una nuova distribuzione
npx wrangler pages publish dist

Dopo aver caricato i file del tuo progetto, Wrangler ti fornirà un URL per visualizzare l’anteprima del tuo sito in anteprima. Quando accedi al pannello di controllo di Cloudflare Pages, vedrai il tuo nuovo progetto.

Abilitazione dell’anteprima in locale con Wrangler

Sezione intitolata Abilitazione dell’anteprima in locale con Wrangler

Per far funzionare l’anteprima, è necessario installare wrangler

Terminal window
pnpm add wrangler --save-dev

A questo punto è possibile aggiornare lo script di preview in modo da utilizzare wrangler, invece del comando di anteprima della CLI di Astro.

package.json
"preview": "wrangler pages dev ./dist"

Come effettuare il deploy di un sito SSR

Sezione intitolata Come effettuare il deploy di un sito SSR

Puoi creare un sito Astro SSR e eseguire il deploy su Cloudflare Pages utilizzando l’adapter @astrojs/cloudflare.

Segui i passaggi qui sotto per configurare l’adapter. Successivamente, puoi effettuare il deploy del tuo sito utilizzando uno dei metodi visti in precedenza.

Aggiungi l’adapter di Cloudflare per abilitare l’SSR nel tuo progetto Astro utilizzando il seguente comando: astro add. Questo installerà l’adapter e apporterà le modifiche appropriate al tuo file astro.config.mjs in un solo passaggio.

Terminal window
npx astro add cloudflare

Se preferisci installare manualmente l’adattatore, segui questi due passaggi:

  1. Aggiungi l’adattatore @astrojs/cloudflare alle dipendenze del tuo progetto utilizzando il tuo package manager preferito. Se stai utilizzando npm o non sei sicuro di quale tu stia utilizzando, esegui questo comando nel terminale:

    Terminal window
    npm install @astrojs/cloudflare
  2. Aggiungi questi parametri al tuo astro.config.mjs:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';
    export default defineConfig({
    output: 'server',
    adapter: cloudflare()
    });

Attualmente sono supportate due modalità quando si utilizzano le Funzioni di Cloudflare Pages con l’adattatore @astrojs/cloudflare.

  1. Modalità avanzata: Questa modalità viene utilizzata quando si vuole eseguire una funzione in modalità advanced, che utilizza il file _worker.js in dist, o in modalità directory in cui le pagine compileranno il worker da una cartella functions nella cartella principale del progetto.

    Se nessuna modalità viene impostata, il valore predefinito è "advanced".

  2. Modalità directory: Questa modalità viene utilizzata quando si desidera eseguire una funzione in modalità directory, il che significa che l’adattatore compilerà la parte lato client della tua app nello stesso modo, ma sposterà lo script del worker in una cartella functions nella cartella principale del progetto. L’adattatore metterà sempre un file [[path]].js in quella cartella, consentendoti di aggiungere plugin e middleware aggiuntivi per le pagine.

    astro.config.mjs
    export default defineConfig({
    adapter: cloudflare({ mode: "directory" }),
    });

Utilizzo delle funzioni di Cloudflare Pages

Sezione intitolata Utilizzo delle funzioni di Cloudflare Pages

Le Funzioni di Pages ti consentono di eseguire codice lato server per abilitare funzionalità dinamiche senza dover usare un server dedicato.

Per iniziare, crea una cartella /functions nella cartella principale del tuo progetto. Scrivendo i file delle tue Funzioni in questa cartella verrà automaticamente generato un worker con funzionalità personalizzate. Per saperne di più sulla scrittura delle Funzioni, consulta la documentazione sulle Funzioni di Cloudflare Pages.

📚 Leggi di più su SSR in Astro.

Se incontri errori, verifica che la versione di node che stai utilizzando sul tuo pc (node -v) corrisponda alla versione che stai specificando nella variabile d’ambiente.

Cloudflare richiede Node v16.13, che è una versione più recente rispetto al requisito minimo di Astro out-of-the-box, quindi assicurati di utilizzare almeno la versione v16.13.

L’hydration lato client potrebbe non riuscire a causa dell’impostazione di Auto Minify di Cloudflare. Se vedi Hydration completed but contains mismatches nella console, assicurati di disabilitare Auto Minify nelle impostazioni di Cloudflare.

Altre Guide di Pubblicazione