@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

Cloudflare 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

Astro 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.

npx astro add cloudflare

pnpm astro add cloudflare

yarn astro add cloudflare

Instalación manual

Primero, añade el adaptador @astrojs/cloudflare a las dependencias de tu proyecto utilizando tu gestor de paquetes preferido.

npm install @astrojs/cloudflare

pnpm add @astrojs/cloudflare

yarn add @astrojs/cloudflare

Luego, añade el adaptador y el modo de renderizado deseado a tu archivo astro.config.mjs:

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

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

Opciones

imageService

Tipo: 'passthrough' | 'cloudflare' | 'compile' | 'custom'
Por defecto: 'compile'

Determina que servicio de imágenes es utilizado por el adaptador. El adaptador utilizará el modo compile 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 existente noop.
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 de astro: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 de workerd de Cloudflare.

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

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

platformProxy

Determina 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.

platformProxy.enabled

Tipo: { enabled?: boolean }
Por defecto: { enabled: false }

La propiedad enabled te permite habilitar el tiempo de ejecución de Cloudflare en astro dev.

platformProxy.configPath

Tipo: { 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

Tipo: { 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

Tipo: { 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 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:

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

export default defineConfig({
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
      configPath: 'wrangler.json',
      experimentalJsonConfig: true,
      persist: './.cache/wrangler/v3',
    },
  }),
});

routes.extend

Esta 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

Tipo: { 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

Tipo: { 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.

export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // Enruta una página prerenderizada a la función SSR para renderizado bajo demanda
        exclude: [{ pattern: '/pagefind/*' }], // Usa la búsqueda pagefind de Starlight, que se genera estáticamente en el tiempo de compilación
      }
    },
  }),
});

`cloudflareModules`

Tipo: true | false
Por defecto: true

Habilita importaciones de módulos .wasm, .bin, y .txt.

Esta funcionalidad está habilitada de forma predeterminada. Si deseas deshabilitarla, establece cloudflareModules: false.

Tiempo de ejecución de Cloudflare

El 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.

Uso

Por ejemplo, si tienes una configuración de variables de entorno en wrangler.toml:

[vars]
MY_VARIABLE = "test"

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:

DB_PASSWORD=myPassword

Puedes acceder a los bindings utilizando los locales de Astro de la siguiente manera:

---
const { env } = Astro.locals.runtime;
---

Puedes acceder al tiempo de ejecución desde los endpoints de la API a través de context.locals:

export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}

Para acceder al valor del binding MY_VARIABLE, añade lo siguiente a tu código:

---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
---

Ve la lista de todos los bindings soportados en la documentación de Cloudflare.

Tipado

wrangler 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.

{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}

Puedes tipar el objeto runtime utilizando Runtime:

/// <reference types="astro/client" />

type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

declare namespace App {
  interface Locals extends Runtime {
    otherLocals: {
      test: string;
    };
  }
}

Plataforma Cloudflare

Encabezados

Puedes 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

Los 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

Puedes 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.

Rutas

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

Crear 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.

Importaciones de Módulos Cloudflare

El tiempo de ejecución del worker de Cloudflare soporta importaciones de algunos tipos de módulos no estándar. La mayoría de los tipos de archivos adicionales también están disponibles en astro:

.wasm o .wasm?module: exporta un WebAssembly.Module que luego puede ser instanciado
.bin: exporta un ArrayBuffer de los contenidos binarios crudos del archivo
.txt: Exporta un string con el contenido del archivo

Todos los tipos de módulos exportan un único valor predeterminado. Los módulos pueden ser importados tanto desde páginas renderizadas en el servidor como desde páginas prerenderizadas para la generación de sitios estáticos.

Lo 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.

// Importa el módulo WebAssembly
import mod from '../util/add.wasm';

// Instancia primero para poder usarlo
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}

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 o una pequeña base de datos pre-indexada para la búsqueda en un conjunto de datos de solo lectura.

Compatibilidad con Node.js

De 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:*'.

export const prerender = false;
import { Buffer } from 'node:buffer';

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:*:

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

export default defineConfig({
  adapter: cloudflare({}),
  output: 'server',
  vite: {
    ssr: {
      external: ['node:buffer'],
    },
  },
})

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.

Vista previa con Wrangler

Para usar wrangler para ejecutar tu aplicación localmente, actualiza el script de vista previa:

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

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

Por 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.

export default defineConfig({
  adapter: cloudflare(),
  output: 'server',
  vite: {
    build: {
      minify: false,
    },
  },
});