@astrojs/ cloudflare

Este adaptador permite que Astro despliegue tus rutas y características renderizadas bajo demanda en Cloudflare, incluyendo islas de servidor, acciones y sesiones.

Si estás usando Astro como un generador de sitios estáticos, no necesitas un adaptador.

Aprende cómo desplegar tu sitio de Astro en nuestra guía de despliegue en Cloudflare.

¿Actualizando a Astro 6?

Astro 6 requiere una actualización a la v13 de este adaptador. Consulta las instrucciones de actualización del adaptador de Cloudflare para Astro 6 para conocer los cambios de ruptura y la guía de migración.

Por qué Astro Cloudflare

La Plataforma de Desarrolladores de Cloudflare te permite desarrollar aplicaciones full-stack con acceso a recursos como almacenamiento e IA, todo desplegado en una red perimetral global. Este adaptador compila tu proyecto de Astro para su 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 el renderizado en el servidor en tu proyecto de Astro con el comando astro add. Esto instalará @astrojs/cloudflare y realizará los cambios apropiados en tu archivo astro.config.mjs en un solo paso.

npm

npx astro add cloudflare

pnpm

pnpm astro add cloudflare

Yarn

yarn astro add cloudflare

Ahora, puedes habilitar el renderizado bajo demanda por página, o establecer la configuración de salida de tu compilación en output: 'server' para renderizar todas tus páginas en el servidor por defecto.

Instalación manual

1. Añade el adaptador @astrojs/cloudflare a las dependencias de tu proyecto usando tu gestor de paquetes preferido.

   npm

   npm install @astrojs/cloudflare

   pnpm

   pnpm add @astrojs/cloudflare

   Yarn

   yarn add @astrojs/cloudflare

2. Añade el adaptador a tu archivo astro.config.mjs:

   astro.config.mjs

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

3. Astro generará automáticamente una configuración por defecto, utilizando el campo name de package.json o el nombre de la carpeta como nombre del Worker. Opcionalmente, puedes crear un archivo de configuración de Wrangler si necesitas configuraciones personalizadas. Este ejemplo declara enlaces de Cloudflare KV:

   wrangler.jsonc

   {
     "name": "my-astro-app",
     // Add your bindings here, e.g.:
     // "kv_namespaces": [{ "binding": "MY_KV", "id": "<namespace_id>" }]
   }

Opciones

El adaptador de Cloudflare acepta las siguientes opciones de @cloudflare/vite-plugin:

• auxiliaryWorkers
• configPath
• inspectorPort
• persistState
• remoteBindings
• experimental.headersAndRedirectsDevModeSupport

También acepta lo siguiente:

imageService

Tipo: 'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }
Predeterminado: 'cloudflare-binding'

Determina qué servicio de imágenes utiliza el adaptador. El adaptador usará por defecto el modo cloudflare-binding cuando se configure un servicio de imágenes incompatible. De lo contrario, utilizará el servicio de imágenes configurado globalmente:

• cloudflare: Utiliza el servicio Cloudflare Image Resizing.
• cloudflare-binding: Utiliza el enlace Cloudflare Images binding para la transformación de imágenes. El enlace se proporciona automáticamente cuando realizas el despliegue.
• passthrough: Utiliza el servicio noop existente.
• compile: Utiliza una combinación de dependencias internas para transformar imágenes localmente en el momento de la compilación para las rutas prerenderizadas. La opción noop passthrough está configurada para páginas renderizadas bajo demanda.
• custom: Utiliza siempre el servicio de imágenes configurado en Opciones de imagen. Esta opción no comprobará si el servicio de imágenes configurado funciona en el entorno de ejecución workerd de Cloudflare.

También es posible configurar tu servicio de imágenes como un objeto, configurando el servicio de tiempo de compilación y de tiempo de ejecución de forma independiente. Actualmente, 'compile' es la única opción de tiempo de compilación disponible. Las opciones de tiempo de ejecución admitidas son 'passthrough' (predeterminado) y 'cloudflare-binding':

astro.config.mjs

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

export default defineConfig({
  adapter: cloudflare({
    imageService: { build: 'compile', runtime: 'cloudflare-binding' }
  }),
});

sessionKVBindingName

Type: string
Default: SESSION

Agregado en: @astrojs/cloudflare@12.4.0

Establece el nombre del enlace KV utilizado para el almacenamiento de sesiones. Por defecto, el espacio de nombres KV se proporciona automáticamente cuando realizas el despliegue y se llama SESSION. Puedes cambiar este nombre configurando el enlace manualmente en tu configuración de wrangler. Consulta Sesiones para obtener más información.

astro.config.mjs

export default defineConfig({
  adapter: cloudflare({
    sessionKVBindingName: 'MY_SESSION_BINDING',
  }),
});

wrangler.jsonc

{
  "kv_namespaces": [
    {
      "binding": "MY_SESSION_BINDING",
    }
  ]
}

imagesBindingName

Type: string
Default: IMAGES

Establece el nombre del enlace de imágenes utilizado cuando imageService está configurado en cloudflare-binding. Por defecto, el enlace se proporciona automáticamente con el nombre IMAGES cuando realizas el despliegue. Puedes cambiarlo configurando el enlace manualmente en tu configuración de wrangler:

astro.config.mjs

export default defineConfig({
  adapter: cloudflare({
    imageService: 'cloudflare-binding',
    imagesBindingName: 'MY_IMAGES',
  }),
});

wrangler.jsonc

{
  "images": {
    "binding": "MY_IMAGES"
  }
}

prerenderEnvironment

Type: 'workerd' | 'node'
Default: 'workerd'

Agregado en: @astrojs/cloudflare@13.1.0

Controla qué entorno de ejecución se utiliza para prerenderizar páginas estáticas en el momento de la compilación y durante el desarrollo.

Por defecto, las páginas prerenderizadas se compilan utilizando el entorno de ejecución workerd de Cloudflare para que coincida lo más estrechamente posible con el entorno de producción. Establece esta opción en 'node' cuando tus páginas prerenderizadas dependan de las API de Node.js o de paquetes de NPM que no sean compatibles con workerd:

astro.config.mjs

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

export default defineConfig({
  adapter: cloudflare({
    prerenderEnvironment: 'node',
  }),
});

Por ejemplo, si una página prerenderizada lee del sistema de archivos utilizando node:fs, establece prerenderEnvironment en 'node'. Las páginas renderizadas bajo demanda no se ven afectadas por esta opción y siempre se ejecutan en workerd.

Entorno de ejecución de Cloudflare

El entorno de ejecución de Cloudflare te brinda acceso a variables de entorno, enlaces a recursos de Cloudflare y otras API específicas de Cloudflare.

Variables de entorno y enlaces

Las variables de entorno y los enlaces se definen en tu archivo de configuración wrangler.jsonc.

Define las variables de entorno que no almacenen información confidencial en wrangler.jsonc:

wrangler.jsonc

{
  "vars": {
    "MY_VARIABLE": "test",
  },
}

Los secrets (secretos) son un tipo especial de variable de entorno que te permite adjuntar valores de texto encriptados a tu Worker. Deben definirse de manera diferente para garantizar que no sean visibles dentro de Wrangler o el panel de control de Cloudflare después de configurarlos.

Para definir secrets, agrégalos a través de la CLI de Wrangler en lugar de en tu archivo de configuración de Wrangler:

npx wrangler secret put <KEY>

Para configurar secretos para el desarrollo local, añade un archivo .dev.vars en la raíz del proyecto de Astro:

.dev.vars

DB_PASSWORD=myPassword

Las variables de entorno y los secretos de Cloudflare se pueden importar desde "cloudflare:workers":

src/pages/index.astro

---
import { env } from 'cloudflare:workers';

const myVariable = env.MY_VARIABLE;
const myKVNamespace = env.MY_KV;
---

También son compatibles con la API astro:env:

import { MY_VARIABLE } from 'astro:env/server';

Consulta la lista de todos los enlaces compatibles en la documentación de Cloudflare.

El objeto cf

El objeto cf de Cloudflare contiene metadatos de la solicitud, como información de geolocalización. Accede a él directamente desde la solicitud:

src/pages/index.astro

---
const cf = Astro.request.cf;
const country = cf?.country;
---

Contexto de ejecución

Accede al ExecutionContext de Cloudflare a través de Astro.locals.cfContext. Esto es útil para operaciones como waitUntil(), o para acceder a las exportaciones de Durable Objects dentro de tu página.

src/pages/index.astro

---
const cfContext = Astro.locals.cfContext;
cfContext.exports.Greeter.greet('Astro');
cfContext.waitUntil(someAsyncOperation());
---

Tipado

wrangler proporciona un comando types para generar tipos de TypeScript para tus enlaces. Esto te permite tipar tu entorno sin necesidad de definiciones de tipos manuales.

Ejecuta wrangler types cada vez que cambies tus archivos de configuración (por ejemplo, wrangler.jsonc, .dev.vars).

Nota

El siguiente ejemplo muestra una configuración de script para ejecutar wrangler types automáticamente antes de otros comandos:

package.json

{
  "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"
  }
}

Plataforma Cloudflare

Cabeceras

Agrega cabeceras personalizadas para archivos estáticos creando un archivo _headers en la carpeta public/ de tu proyecto de Astro. Este archivo se copiará al directorio de salida de la compilación. Las cabeceras en _headers no se aplican a las respuestas generadas por el código de tu Worker.

Archivos estáticos

Los archivos estáticos compilados por Astro se nombran con un hash y, por lo tanto, se les pueden asignar cabeceras de caché de larga duración. Por defecto, Astro en Cloudflare agregará dicha cabecera para estos archivos.

Redirecciones

Declara redirecciones personalizadas para archivos estáticos agregando un archivo _redirects en la carpeta public/ de tu proyecto de Astro. Este archivo se copiará a tu directorio de salida de la compilación. Para rutas dinámicas, configura las redirecciones directamente en Astro en su lugar.

Rutas

El enrutamiento para archivos estáticos se basa en la estructura de archivos en el directorio de compilación (por ejemplo, ./dist). Si no se encuentra ninguna coincidencia, se recurrirá al Worker para el renderizado bajo demanda. Lee más sobre el enrutamiento de archivos estáticos con Cloudflare Workers.

Sesiones

La API de Sesiones de Astro te permite almacenar fácilmente datos de usuario entre solicitudes. Esto se puede usar para cosas como datos y preferencias de usuario, carritos de compras y credenciales de autenticación. A diferencia del almacenamiento en cookies, no hay límites de tamaño en los datos y se pueden restaurar en diferentes dispositivos.

Astro configura automáticamente Workers KV para el almacenamiento de sesiones cuando se utiliza el adaptador de Cloudflare. Wrangler puede proporcionar automáticamente el espacio de nombres KV cuando realizas el despliegue, por lo que no se requiere configuración manual. Alternativamente, puedes definir el enlace KV manualmente en tu archivo wrangler.jsonc y establecer un nombre de enlace personalizado utilizando la opción del adaptador sessionKVBindingName.

src/components/CartButton.astro

---
export const prerender = false; // Not needed in 'server' mode
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

Por defecto, el enlace KV se llama SESSION. Para usar un nombre diferente, establece la opción sessionKVBindingName en la configuración del adaptador.

Nota

Las escrituras en Cloudflare KV son eventualmente consistentes entre regiones. Esto significa que los cambios están disponibles de inmediato dentro de la misma región, pero pueden tardar hasta 60 segundos en propagarse globalmente. Esto no afectará a la mayoría de los usuarios, ya que es poco probable que cambien de región entre solicitudes, pero puede ser una consideración para algunos casos de uso, como los usuarios de VPN.

Importaciones de módulos de Cloudflare

El entorno de ejecución workerd de Cloudflare admite la importación 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 se puede instanciar
• .bin: exporta un ArrayBuffer del contenido binario sin procesar del archivo
• .txt: exporta una cadena de texto con el contenido del archivo

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

El siguiente es un ejemplo de importación de un módulo Wasm que luego responde a las solicitudes sumando los parámetros numéricos de la solicitud.

pages/add/[a]/[b].js

// Import the WebAssembly module
import mod from '../util/add.wasm';

// Instantiate first in order to use it
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)}`);
}

Aunque este ejemplo es trivial, Wasm se puede utilizar para acelerar operaciones computacionalmente intensivas que no involucran I/O significativas, como integrar una biblioteca de procesamiento de imágenes o integrar una pequeña base de datos preindexada para búsquedas sobre un conjunto de datos de solo lectura.

Compatibilidad con Node.js

Cloudflare Workers admite la mayoría de las API del entorno de ejecución de Node.js a través de la bandera de compatibilidad nodejs_compat. Esto incluye módulos de uso común como node:buffer, node:crypto, node:path y muchos otros. Consulta la lista completa de las API de Node.js compatibles en la documentación de Cloudflare.

Para habilitar la compatibilidad con Node.js, agrega la bandera nodejs_compat a tu configuración de Wrangler:

wrangler.jsonc

{
  "compatibility_flags": ["nodejs_compat"],
}

Luego usa la sintaxis de importación node:* en tu código del lado del servidor:

src/pages/api/endpoint.js

export const prerender = false; // Not needed in 'server' mode
import { Buffer } from 'node:buffer';

Para las API de Node.js que aún no son compatibles con el entorno de ejecución de Workers, Wrangler puede inyectar polyfills (requiere nodejs_compat y una fecha de compatibilidad del 23 de septiembre de 2024 o posterior).

Consulta la documentación de Cloudflare sobre la compatibilidad con Node.js para obtener la lista completa de las API compatibles y detalles de configuración.

Vista previa local

Después de compilar tu proyecto con astro build, usa astro preview para probar tu aplicación de Cloudflare Workers localmente. La vista previa se ejecuta utilizando el entorno de ejecución workerd de Cloudflare, reflejando de cerca el comportamiento de producción.

Mensajes de error significativos

Por defecto, los errores que ocurren al ejecutar tu aplicación en Wrangler se minimizan. Para una mejor depuración, agrega vite.build.minify = false a tu astro.config.mjs:

astro.config.mjs

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

Uso de enrutamiento avanzado

Agregado en: @astrojs/cloudflare@13.6.0

El adaptador de Cloudflare proporciona manejadores complementarios que aplican la configuración específica de Cloudflare a tu canalización de enrutamiento avanzada. Estos manejadores configuran la inyección de enlace KV de sesión, el servicio de archivos estáticos a través del enlace ASSETS, Astro.locals.cfContext, la dirección del cliente desde la cabecera cf-connecting-ip, waitUntil y la recuperación de páginas de error prerenderizadas.

Puedes usar las API astro/fetch y astro/hono de src/fetch.ts en Cloudflare sin estos manejadores. El punto de entrada predeterminado del adaptador se encarga de la configuración específica de Cloudflare por ti. Estos manejadores complementarios son útiles cuando ya tienes un punto de entrada de worker personalizado (src/worker.ts), por ejemplo, para exportar un Durable Object, y deseas usar las API de enrutamiento avanzadas directamente desde ese archivo en su lugar.

Al usar estos manejadores en tu punto de entrada del worker, reemplazan la funcionalidad del manejador por defecto del adaptador, por lo que no debes usar ambos al mismo tiempo. Coloca el manejador de Cloudflare antes de otros manejadores de Astro para que los enlaces y los locales estén disponibles para el resto de la canalización.

Con la Fetch API

Agregado en: @astrojs/cloudflare@13.6.0

Para su uso con astro/fetch. La función cf() importada desde @astrojs/cloudflare/fetch recibe un FetchState, el env de Cloudflare y el ExecutionContext. Devuelve una Response para los aciertos de archivos estáticos, o undefined cuando la solicitud debe continuar con el renderizado de Astro:

src/worker.ts

import { astro, FetchState } from 'astro/fetch';
import { cf } from '@astrojs/cloudflare/fetch';

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const state = new FetchState(request);
    const asset = await cf(state, env, ctx);
    if (asset) return asset;
    return astro(state);
  },
};

Con Hono

Agregado en: @astrojs/cloudflare@13.6.0

Para su uso con astro/hono. La función cf() importada desde @astrojs/cloudflare/hono devuelve un middleware de Hono que lee env y executionCtx del contexto de Hono automáticamente:

src/worker.ts

import { Hono } from 'hono';
import { actions, middleware, pages, i18n } from 'astro/hono';
import { cf } from '@astrojs/cloudflare/hono';

const app = new Hono<{ Bindings: Env }>();

app.use(cf());
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());

export default app;

Actualizando a v13 y Astro 6

Astro 6 aporta mejoras significativas a la experiencia de desarrollo en Cloudflare y requiere @astrojs/cloudflare v13 o posterior. Ahora, astro dev utiliza el plugin de Vite para Cloudflare y el entorno de ejecución workerd para emular fielmente el comportamiento de producción.

Consulta la guía de actualización de Astro 6 para obtener instrucciones completas sobre cómo actualizar el propio Astro.

El servidor de desarrollo ahora usa workerd

El mayor cambio para los usuarios de Cloudflare en Astro 6 es que astro dev y astro preview ahora usan el plugin de Vite para Cloudflare para ejecutar tu sitio utilizando el entorno de ejecución real de Workers (workerd) en lugar de Node.js. Esto significa que tu entorno de desarrollo es ahora una réplica mucho más cercana de tu entorno de producción, con el mismo entorno de ejecución, API y comportamiento.

Este cambio te ayuda a detectar problemas durante el desarrollo que anteriormente solo habrían aparecido en producción, y características como Durable Objects, enlaces R2 y Workers AI ahora funcionan exactamente igual que cuando se despliegan en la plataforma de Cloudflare.

Este cambio es transparente para la mayoría de los proyectos. Si tu proyecto tenía una configuración especial para astro dev o dependía de un comportamiento específico de Node.js en el desarrollo, ajusta tu código o configuración en consecuencia.

Nuevo: opción prerenderEnvironment

En Astro 6, las páginas prerenderizadas ahora se ejecutan en el entorno de ejecución workerd de Cloudflare por defecto durante el desarrollo y la compilación. Anteriormente, estas páginas siempre se ejecutaban en Node.js.

Si tus páginas prerenderizadas dependen de las API de Node.js (por ejemplo, node:fs) o de paquetes de NPM que no son compatibles con workerd, establece prerenderEnvironment: 'node' en la configuración de tu adaptador de Cloudflare para restaurar el comportamiento anterior para la prerenderización.

Las páginas renderizadas bajo demanda no se ven afectadas por esta opción y continúan ejecutándose en workerd.

Consulta prerenderEnvironment para obtener detalles de configuración.

Es posible que sea necesario precompilar algunas dependencias

El nuevo entorno de workerd no admite la sintaxis CommonJS, incluida la sintaxis específica de Node.js como require y module.exports. Esto significa que algunas de las dependencias de tu proyecto pueden lanzar errores en el servidor de desarrollo o durante la compilación.

Si tienes control sobre la dependencia, puedes crear un plugin de Vite y precompilar la dependencia usando la opción optimizeDeps.include.

Por ejemplo, puedes crear un plugin de Vite para precompilar la dependencia postcss para poder usar el resaltador de sintaxis Expressive Code:

function noExternalPlugin() {
  return {
    name: "optimize-dependencies",
    configEnvironment(environment) {
      // We're only interested in server environments
      if (environment !== 'client') {
        return {
          optimizeDeps: {
            include: [
              "postcss"
              // Or you can use this syntax if you don't depend directly on a dependency
              // "expressive-code > postcss"
            ]
          }
        }
      }
    }
  }
}

Cambiado: Configuración del punto de entrada de Wrangler

Anteriormente, el campo main en tu configuración de Wrangler apuntaba al archivo de worker compilado (por ejemplo, dist/_worker.js/index.js). Con Astro 6, esto ha cambiado para apuntar a un nuevo punto de entrada unificado proporcionado por el adaptador de Cloudflare: @astrojs/cloudflare/entrypoints/server.

Actualiza tu wrangler.jsonc para usar el nuevo punto de entrada:

wrangler.jsonc

{
  "main": "dist/_worker.js/index.js",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "name": "my-astro-app",
  // ... rest of config
}

Este único punto de entrada maneja tanto astro dev como los despliegues de producción.

Eliminado: API Astro.locals.runtime

El objeto Astro.locals.runtime se ha eliminado a favor del acceso directo a las API de Cloudflare Workers. Accede a las variables de entorno, al objeto cf, a las cachés y al contexto de ejecución directamente a través de las interfaces proporcionadas.

Accessing environment variables:

Anteriormente, se accedía a las variables de entorno a través de Astro.locals.runtime.env. Ahora importa env directamente en su lugar:

const { env } = Astro.locals.runtime;
import { env } from 'cloudflare:workers';

Accessing the cf object:

Anteriormente, se accedía al objeto cf a través de Astro.locals.runtime.cf. Ahora accede a él directamente desde la solicitud:

const { cf } = Astro.locals.runtime;
const cf = Astro.request.cf;

Accessing the caches API:

Anteriormente, se accedía a la API de cachés a través de Astro.locals.runtime.caches. Ahora usa el objeto global caches directamente:

const { caches } = Astro.locals.runtime;

caches.default.put(request, response);

Accessing the execution context:

El objeto Astro.locals.runtime.ctx se reemplaza por Astro.locals.cfContext, que contiene el ExecutionContext de Cloudflare:

const ctx = Astro.locals.runtime.ctx;
const ctx = Astro.locals.cfContext;

Cambiado: El archivo de configuración de Wrangler ahora es opcional

El archivo de configuración de Wrangler ahora es opcional para proyectos sencillos. Si no tienes una configuración personalizada, como enlaces de Cloudflare (KV, D1, Durable Objects, etc.), Astro generará automáticamente una configuración por defecto para ti.

Si tu wrangler.jsonc solo contiene una configuración básica como esta:

{
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2025-05-21",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
  },
}

Puedes eliminar este archivo de forma segura. Astro maneja esta configuración automáticamente. Alternativamente, crea un wrangler.jsonc mínimo con solo el nombre de tu proyecto y otras configuraciones personalizadas:

wrangler.jsonc

{
  "name": "my-astro-app",
}

Cambiado: API de punto de entrada personalizada

Si estabas usando una configuración de workerEntryPoint personalizada en las opciones del adaptador, esta se ha eliminado. En su lugar, especifica tu punto de entrada personalizado en tu configuración de Wrangler y crea un objeto de exportación estándar de Cloudflare Worker directamente, en lugar de usar la función createExports().

1. Elimina la opción workerEntryPoint de la configuración de tu adaptador:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import cloudflare from '@astrojs/cloudflare';
   
   export default defineConfig({
     adapter: cloudflare({
       workerEntryPoint: {
         path: 'src/worker.ts',
         namedExports: ['MyDurableObject'],
       },
     }),
   });

2. Especifica el punto de entrada en wrangler.jsonc en su lugar:

   wrangler.jsonc

   {
     "main": "./src/worker.ts"
   }

3. Actualiza tu archivo de entrada de worker personalizado para usar la sintaxis estándar de Worker. Importa el manejador desde @astrojs/cloudflare/handler y exporta un objeto estándar de Cloudflare Worker, junto con cualquier exportación personalizada como Durable Objects:

   src/worker.ts

   import { handle } from '@astrojs/cloudflare/handler';
   import { DurableObject } from 'cloudflare:workers';
   
   export class MyDurableObject extends DurableObject<Env> {
     // ...
   }
   
   export default {
     async fetch(request, env, ctx) {
       await env.MY_QUEUE.send('log');
       return handle(request, env, ctx);
     },
     async queue(batch, _env) {
       let messages = JSON.stringify(batch.messages);
       console.log(`consumed from our queue: ${messages}`);
     },
   } satisfies ExportedHandler<Env>;

El manifiesto ahora se crea internamente por el adaptador, por lo que no es necesario pasarlo a tu manejador.

Eliminado: opción cloudflareModules

La opción del adaptador cloudflareModules se ha eliminado porque ya no es necesaria. Cloudflare admite de forma nativa la importación de .sql, .wasm y otros tipos de módulos.

Elimina la opción cloudflareModules de la configuración de tu adaptador de Cloudflare si la estabas usando:

astro.config.mjs

import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    cloudflareModules: true
  })
});

Nuevo: soporte para astro preview

Usa astro preview para probar tu aplicación de Cloudflare Workers localmente antes de desplegar. La vista previa se ejecuta utilizando el entorno de ejecución workerd de Cloudflare, reflejando de cerca el comportamiento de producción. Ejecuta astro build seguido de astro preview para iniciar el servidor de vista previa.

Eliminado: Soporte para Cloudflare Pages

El adaptador de Astro Cloudflare ya no admite el despliegue en Cloudflare Pages. Para obtener la mejor experiencia y soporte de características, debes migrar a Cloudflare Workers.

Consulta la guía de migración de Pages a Workers de Cloudflare para obtener instrucciones detalladas de migración.

Cambiado: valor predeterminado de imageService

El valor por defecto de imageService ha cambiado de 'compile' a 'cloudflare-binding' para una mejor experiencia al trabajar con imágenes.

El servicio cloudflare-binding utiliza el enlace Cloudflare Images binding para transformar imágenes en tiempo de ejecución, y el enlace se proporciona automáticamente cuando realizas el despliegue.

Para volver al comportamiento anterior, donde la transformación de imágenes solo estaba disponible en rutas prerenderizadas en el momento de la compilación, establece imageService: 'compile' explícitamente en la configuración de tu adaptador.

Cambiado: Desplegar en el entorno de Cloudflare

En Astro 5.x, podías compilar tu proyecto de Astro una vez y desplegarlo en un entorno de Cloudflare específico con wrangler deploy --env some-env.

Desde Astro 6.0, la integración depende del plugin de Vite para Cloudflare y este comportamiento ha cambiado. El entorno ahora se determina durante la fase de compilación. Por lo tanto, debes compilar tu proyecto por separado para cada entorno.

Para desplegar en un entorno de Cloudflare específico, antepone a tu comando la variable CLOUDFLARE_ENV. Por ejemplo, el comando CLOUDFLARE_ENV=some-env astro build && wrangler deploy compilará tu proyecto de Astro y lo desplegará con Wrangler utilizando el entorno some-env.

Aprende cómo actualizar tus entornos de Cloudflare en la guía de migración desde wrangler dev.

Más integraciones

Frameworks de front-end

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptadores

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Otras integraciones

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap