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:

Come effettuare il deploy tramite il Pannello di controllo di Cloudflare Pages
Come effettuare il deploy utilizzando Wrangler, la CLI di Cloudflare
Come effettuare il deploy di un sito SSR utilizzando @astrojs/cloudflare

Prerequisiti

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

Configura un nuovo progetto su Cloudflare Pages.
Esegui il push del tuo codice nel tuo repository Git (GitHub, GitLab).
Accedi al pannello di controllo di Cloudflare e seleziona il tuo account in Account Home > Pages.
Clicca su Crea applicazione e dopo sull’opzione Esegui la connessione a Git.
Seleziona il progetto git che desideri pubblicare e clicca su Inizia configurazione.
Utilizza le seguenti impostazioni per la build:
- Framework preimpostato: Astro
- Comando di build: npm run build
- Directory di output della build: dist
Clicca il pulsante Salva e Distribuisci.

Come effettuare il deploy di un sito utilizzando Wrangler

Installa Wrangler.
Esegui il login con il tuo account Cloudflare utilizzando il comando wrangler login.
Esegui il comando per avviare la build.
Effettua il deploy utilizzando il comando npx wrangler pages publish dist.

# 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 deploy 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

Per far funzionare l’anteprima, è necessario installare wrangler

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.

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

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.

Installazione rapida

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.

npx astro add cloudflare

Installazione manuale

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

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
```

Aggiungi questi parametri al tuo astro.config.mjs:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});

Leggi di più su SSR in Astro.

Risoluzione dei problemi

Idratazione lato client

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

API di runtime Node.js

Se stai costruendo un progetto che utilizza il rendering on-demand con l’adattatore SSR di Cloudflare e il server non riesce a compilare con un messaggio di errore come [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.:

Questo significa che un pacchetto o un’importazione che stai utilizzando nell’ambiente lato server non è compatibile con le API di runtime di Cloudflare.
Se stai importando direttamente un’API di runtime Node.js, consulta la documentazione di Astro sulla compatibilità Node.js di Cloudflare per ulteriori passaggi su come risolvere questo problema.
Se stai importando un pacchetto che importa un’API di runtime Node.js, verifica con l’autore del pacchetto se supporta la sintassi di importazione node:*. Se non lo fanno, potresti dover trovare un pacchetto alternativo.