@astrojs/ cloudflare
Este adaptador permite a Astro desplegar tu sitio renderizado de manera hybrid
o server
en Cloudflare.
Si estás utilizando Astro como un constructor de sitios estáticos, no necesitas un adaptador.
Aprende como desplegar tu sitio en nuestra guía de despliegue en Cloudflare Pages.
Por qué Astro Cloudflare
Sección titulada Por qué Astro CloudflareCloudflare porporciona CDNs, seguridad web y otros servicios. Este adaptador mejora el proceso de compilación de Astro para preparar tu proyecto para el despliegue a través de Cloudflare.
Instalación
Sección titulada InstalaciónAstro incluye un comando astro add
para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.
Añade el adaptador de Cloudflare para habilitar SSR en tu proyecto de Astro con el comando astro add
. Esto instalará @astrojs/cloudflare
y realizará los cambios correspondientes en tu archivo astro.config.mjs
en un solo paso.
Instalación manual
Sección titulada Instalación manualPrimero, añade el adaptador @astrojs/cloudflare
a las dependencias de tu proyecto utilizando tu gestor de paquetes preferido.
Luego, añade el adaptador y el modo de renderizado deseado a tu archivo astro.config.mjs
:
Opciones
Sección titulada OpcionesimageService
Sección titulada imageServiceTipo: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
Por defecto: 'passthrough'
Determina que servicio de imágenes es utilizado por el adaptador. El adaptador utilizará el modo passthrough
de forma predeterminada cuando se configure un servicio de imágenes incompatible. De lo contrario, utilizará el servicio de imágenes configurado globalmente:
cloudflare
: Usa el servicio de Redimensionamiento de Imagen de Cloudflare.
passthrough
: Usa el servicio existentenoop
.compile
: Usa el servicio predeterminado de Astro (sharp), pero solo en rutas pre-renderizadas durante el tiempo de compilación. Durante el SSR para páginas renderizadas según demanda, todas las características deastro:assets
están desactivadas.custom
: Siempre usa el servicio de imágenes configurado en Opciones de Imágenes. Esta opción no comprobará si el servicio de imágenes configurado funciona en el tiempo de ejecución deworkerd
de Cloudflare.
platformProxy
Sección titulada platformProxyDetermina si y como el tiempo de ejecución de Cloudflare es añadido a astro dev
. Contiene proxies a los bindings locales de workerd
y emulaciones de valores específicos de Cloudflare, permitiendo la emulación del tiempo de ejecución en el proceso de desarrollo de Node.js. Lee más sobre el tiempo de ejecución de Cloudflare.
Los proxies proporcionados por esto son una emulación del mejor esfuerzo de la producción real. Aunque están diseñados para ser lo más cercanos posible a la realidad, puede haber pequeñas diferencias e inconsistencias entre los dos.
platformProxy.enabled
Sección titulada platformProxy.enabledTipo: { enabled?: boolean }
Por defecto: { enabled: false }
La propiedad enabled
te permite habilitar el tiempo de ejecución de Cloudflare en astro dev
.
platformProxy.configPath
Sección titulada platformProxy.configPathTipo: { configPath?: string }
Por Defecto: { configPath: 'wrangler.toml' }
La propiedad configPath
te permite definir tu archivo de configuración de Wrangler, relativo a la raíz de tu proyecto de Astro.
platformProxy.experimentalJsonConfig
Sección titulada platformProxy.experimentalJsonConfigTipo: { experimentalJsonConfig?: boolean }
Por Defecto: { experimentalJsonConfig?: false }
La propiedad experimentalJsonConfig
define si la utilidad lee un archivo de configuración JSON (por ejemplo, wrangler.json
).
platformProxy.persist
Sección titulada platformProxy.persistTipo: { persist?: boolean | { path: string } }
Por Defecto: { persist: true }
La propiedad persists
define si y donde los datos de los bindings son persistentes. true
se establece en la misma ubicación utilizada por Wrangler para que los datos puedan ser compartidos entre los dos. Si es false
, los datos no persisten ni se leen del sistema de archivos.
La opción --persist-to
de wrangler
añade un subdirectorio llamado v3
bajo el capó, mientras que la propiedad persist
de @astrojs/cloudflare
no lo hace. Por ejemplo, para reutilizar la misma ubicación que al ejecutar wrangler dev --persist-to ./my-directory
, debes especificar: persist: "./my-directory/v3"
.
La siguiente configuración muestra un ejemplo de cómo habilitar el tiempo de ejecución de Cloudflare al ejecutar el servidor de desarrollo, así como el uso de un archivo de configuración wrangler.json
(experimental). También especifica una ubicación personalizada para persistir los datos en el sistema de archivos:
routes.extend
Sección titulada routes.extendEsta opción te permite añadir o excluir patrones personalizados (por ejemplo, /fonts/*
) al archivo _routes.json
generado que determina qué rutas se generan bajo demanda. Esto puede ser útil si necesitas añadir patrones de rutas que no se pueden generar automáticamente, o excluir rutas pre-renderizadas.
Para mayor información acerca de los patrones de rutas personalizados, puedes consultar la documentación de enrutamiento de Cloudflare. Cualquier ruta especificada no se deduplicará automáticamente y se añadirá a las rutas existentes tal cual.
routes.extend.include
Sección titulada routes.extend.includeTipo: { pattern: string }[]
Por defecto: undefined
Configura rutas adicionales para ser generadas bajo demanda por el adaptador de Cloudflare en el array routes.extend.include
.
routes.extend.exclude
Sección titulada routes.extend.excludeTipo: { pattern: string }[]
Por defecto: undefined
Configura rutas para ser excluidas de la generación bajo demanda en el array routes.extend.exclude
. Estas rutas se prerenderizarán y se servirán estáticamente en su lugar, y no invocarán la función SSR. Además, puedes usar esta opción para servir cualquier archivo de activo estático (por ejemplo, imágenes, fuentes, css, js, html, txt, json, etc.) directamente sin enrutar la solicitud a través de la función SSR.
wasmModuleImports
Sección titulada wasmModuleImportsTipo: true | false
Por defecto: false
Importar o no archivos .wasm
directamente como módulos ES usando la sintaxis de importación .wasm?module
.
Añade wasmModuleImports: true
a astro.config.mjs
para habilitar esta funcionalidad tanto en la compilación de Cloudflare como en el servidor de desarrollo de Astro. Lee más sobre el uso de módulos Wasm
Tiempo de ejecución de Cloudflare
Sección titulada Tiempo de ejecución de CloudflareEl tiempo de ejecución de Cloudflare te da acceso a las variables de entorno y a los bindings de Cloudflare.
El tiempo de ejecución de Cloudflare utiliza los bindings encontrados en los archivos de configuración wrangler
y .dev.vars
.
Por ejemplo, si tienes una configuración de variables de entorno en wrangler.toml
:
Si también necesitas definir secrets
además de las variables de entorno, necesitas añadir un archivo .dev.vars
a la raíz del proyecto de Astro:
Puedes acceder a los bindings utilizando los locales de Astro de la siguiente manera:
Puedes acceder al tiempo de ejecución desde los endpoints de la API a través de context.locals
:
Para acceder al valor del binding MY_VARIABLE
, añade lo siguiente a tu código:
Ve la lista de todos los bindings soportados en la documentación de Cloudflare.
Tipado
Sección titulada Tipadowrangler
proporciona un comando types
para generar tipos de TypeScript para los bindings. Esto te permite tipar los locales sin necesidad de hacerlo manualmente. Consulta la documentación de Cloudflare para obtener más información.
Cada vez que cambies tus archivos de configuración (por ejemplo, wrangler.toml
, .dev.vars
) necesitas ejecutar wrangler types
.
Puedes crear un script de pnpm para ejecutar wrangler types
automáticamente antes de otros comandos.
Puedes tipar el objeto runtime
utilizando Runtime
:
Plataforma Cloudflare
Sección titulada Plataforma CloudflareEncabezados
Sección titulada EncabezadosPuedes añadir encabezados personalizados a tus respuestas añadiendo un archivo _headers
en la carpeta public/
de tu proyecto de Astro. Este archivo se copiará al directorio de salida de tu compilación.
Assets
Sección titulada AssetsLos assets construidos por Astro tienen todos un nombre con un hash y, por lo tanto, pueden recibir encabezados de caché largos. De forma predeterminada, Astro en Cloudflare añadirá un encabezado de este tipo para estos archivos.
Redirecciones
Sección titulada RedireccionesPuedes declarar redirecciones personalizadas usando Cloudflare Pages. Esto te permite redirigir solicitudes a una URL diferente. Puedes añadir un archivo _redirects
en la carpeta public/
de tu proyecto de Astro. Este archivo se copiará al directorio de salida de tu compilación.
El enrutamiento de Cloudflare utiliza un archivo _routes.json
para determinar qué solicitudes se enrutan a la función SSR y cuáles se sirven como activos estáticos. De forma predeterminada, se generará automáticamente un archivo _routes.json
para tu proyecto basado en sus archivos y configuración.
Puedes especificar patrones de enrutamiento adicionales en tu configuración de adaptador, o crear tu propio archivo _routes.json
personalizado para anular completamente la generación automática.
_routes.json
personalizado
Sección titulada _routes.json personalizadoCrear un archivo _routes.json
personalizado en la carpeta public/
de tu proyecto de Astro anulará la generación automática. Consulta la documentación de Cloudflare para obtener más detalles.
Usar módulos Wasm
Sección titulada Usar módulos WasmLo siguiente es un ejemplo de importación de un módulo Wasm que responde a las solicitudes sumando los parámetros numéricos de la solicitud.
Mientras que este ejemplo es trivial, Wasm puede ser utilizado para acelerar operaciones computacionalmente intensivas que no involucran una E/S significativa, como incrustar una biblioteca de procesamiento de imágenes.
Compatibilidad con Node.js
Sección titulada Compatibilidad con Node.jsDe forma predeterminada, Cloudflare no soporta las APIs de tiempo de ejecución de Node.js. Con alguna configuración, Cloudflare sí soporta un subconjunto de las APIs de tiempo de ejecución de Node.js. Puedes encontrar las APIs de tiempo de ejecución de Node.js soportadas en la documentación de Cloudflare.
Para usar estas APIs, tu página o endpoint debe ser renderizado en el servidor (no pre-renderizado) y debe usar la sintaxis de importación import {} from 'node:*'
.
También necesitarás modificar la configuración de vite
en tu archivo de configuración de Astro para permitir la sintaxis de importación node:*
:
Adicionalmente, necesitarás seguir la documentación de Cloudflare sobre cómo habilitar el soporte. Para obtener orientación detallada, consulta la documentación de Cloudflare sobre cómo habilitar la compatibilidad con Node.js.
Si un proyecto importa un paquete en el servidor que utiliza las APIs de tiempo de ejecución de Node.js, esto puede causar problemas al desplegar en Cloudflare. Este problema surge con los paquetes que no utilizan la sintaxis de importación node:*
. Se recomienda que contactes a los autores del paquete para determinar si el paquete soporta la sintaxis de importación anterior. Si el paquete no soporta esto, es posible que necesites utilizar un paquete diferente.
Vista previa con Wrangler
Sección titulada Vista previa con WranglerPara usar wrangler
para ejecutar tu aplicación localmente, actualiza el script de vista previa:
wrangler
te da acceso a bindings de Cloudflare, variables de entorno, y al objeto cf. Hacer que la recarga en caliente o que el servidor astro dev
funcione con Wrangler podría requerir una configuración personalizada. Consulta ejemplos de la comunidad
Mensajes de error significativos
Sección titulada Mensajes de error significativosPor el momento, los errores durante la ejecución de tu aplicación en Wrangler no son muy útiles, debido a la minificación de tu código. Para una mejor depuración, puedes añadir la configuración vite.build.minify = false
a tu astro.config.mjs
.