From 2f87dd2ba6c6a15e1f89a170264bdbb5246b9fd7 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Tue, 23 Dec 2025 17:25:51 +0000 Subject: [PATCH 1/6] Add Cloudflare Astro 6 docs --- .../guides/integrations-guide/cloudflare.mdx | 726 ++++++++---------- src/content/docs/en/guides/upgrade-to/v6.mdx | 6 +- 2 files changed, 342 insertions(+), 390 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 60dd13a2e518b..2e5354ea5afb0 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -12,7 +12,7 @@ i18nReady: true import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import ReadMore from '~/components/ReadMore.astro'; import Since from '~/components/Since.astro'; -import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; +import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components'; This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Cloudflare](https://www.cloudflare.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/). @@ -20,11 +20,15 @@ If you're using Astro as a static site builder, you don't need an adapter. Learn how to deploy your Astro site in our [Cloudflare deployment guide](/en/guides/deploy/cloudflare/). + + ## Why Astro Cloudflare Cloudflare's [Developer Platform](https://developers.cloudflare.com/) lets you develop full-stack applications with access to resources such as storage and AI, all deployed to a global edge network. This adapter builds your Astro project for deployment through Cloudflare. - ## Installation Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead. @@ -77,43 +81,26 @@ Now, you can enable [on-demand rendering per page](/en/guides/on-demand-renderin 2. Add the adapter to your `astro.config.mjs` file: - ```js title="astro.config.mjs" ins={2,5} - import { defineConfig } from 'astro/config'; - import cloudflare from '@astrojs/cloudflare'; + ```js title="astro.config.mjs" ins={2,5} + import { defineConfig } from 'astro/config'; + import cloudflare from '@astrojs/cloudflare'; - export default defineConfig({ - adapter: cloudflare(), - }); - ``` + export default defineConfig({ + adapter: cloudflare(), + }); + ``` -3. Create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/): +3. Optionally, create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings, or to declare Cloudflare bindings (KV, D1, Durable Objects, etc.): - ```jsonc title="wrangler.jsonc" - { - "main": "dist/_worker.js/index.js", - "name": "my-astro-app", - // Update to today's date - "compatibility_date": "2025-03-25", - "compatibility_flags": [ - "nodejs_compat", - "global_fetch_strictly_public" - ], - "assets": { - "binding": "ASSETS", - "directory": "./dist" - }, - "observability": { - "enabled": true - } - } - ``` - -4. Create a `.assetsignore` file in your `public/` folder, and add the following lines to it: + ```jsonc title="wrangler.jsonc" + { + "name": "my-astro-app", + // Add your bindings here, e.g.: + // "kv_namespaces": [{ "binding": "MY_KV", "id": "" }] + } + ``` - ```txt title="public/.assetsignore" - _worker.js - _routes.json - ``` + For simple projects without bindings, you can skip this step as Astro will generate a default configuration automatically. The Worker name will be based on the `package.json` name field or the folder name. @@ -124,8 +111,9 @@ The Cloudflare adapter accepts the following options: ### `cloudflareModules`

-**Type:** `boolean`
-**Default:** `true` + **Type:** `boolean` +
+ **Default:** `true`

Enables [imports of `.wasm`, `.bin`, and `.txt` modules](#cloudflare-module-imports). @@ -135,142 +123,40 @@ This functionality is enabled by default. If you'd like to disable, set `cloudfl ### `imageService`

-**Type:** `'passthrough' | 'cloudflare' | 'compile' | 'custom'`
-**Default:** `'compile'` + **Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom'` +
+ **Default:** `'compile'`

Determines which image service is used by the adapter. The adapter will default to `compile` mode when an incompatible image service is configured. Otherwise, it will use the globally configured image service: -* **`cloudflare`:** Uses the [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) service. -* **`passthrough`:** Uses the existing [`noop`](/en/guides/images/#configure-no-op-passthrough-service) service. -* **`compile`:** Uses Astro's default service (sharp), but only on pre-rendered routes at build time. For pages rendered on-demand, all `astro:assets` features are disabled. -* **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options). **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.** +- **`cloudflare`:** Uses the [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) service. +- **`cloudflare-binding`:** Uses the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) for image transformation. The binding is automatically provisioned when you deploy. +- **`passthrough`:** Uses the existing [`noop`](/en/guides/images/#configure-no-op-passthrough-service) service. +- **`compile`:** Uses Astro's default service (sharp), but only on pre-rendered routes at build time. For pages rendered on-demand, all `astro:assets` features are disabled. +- **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options). **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.** ```js title="astro.config.mjs" ins={6} -import { defineConfig } from "astro/config"; -import cloudflare from '@astrojs/cloudflare'; - -export default defineConfig({ - adapter: cloudflare({ - imageService: 'cloudflare' - }), -}) -``` - -### `platformProxy` - -Determines whether and how the Cloudflare runtime is added to `astro dev`. It contains proxies to local `workerd` bindings and emulations of Cloudflare specific values, allowing the emulation of the runtime in the Node.js dev process. Read more about the [Cloudflare Runtime](#cloudflare-runtime). - -:::note -Proxies provided by this are a best effort emulation of the real production. Although they are designed to be as close as possible to the real thing, there might be a slight differences and inconsistencies between the two. -::: - -#### `platformProxy.enabled` -

-**Type:** `boolean`
-**Default:** `true` -

- -Determines whether to enable the Cloudflare runtime in development mode. - -#### `platformProxy.configPath` -

-**Type:** `string`
-**Default:** `undefined` -

- -Defines the path to the Wrangler configuration file. If no value is set, it tracks `wrangler.toml`, `wrangler.json`, and `wrangler.jsonc` in the project root. - -#### `platformProxy.environment` -

-**Type:** `string`
-**Default:** `undefined` -

- -Sets the [Cloudflare environment](https://developers.cloudflare.com/workers/wrangler/environments/) to use. You must select an environment defined in the Wrangler configuration file, otherwise an error occurs. - -#### `platformProxy.persist` -

-**Type:** `boolean | { path: string }`
-**Default:** `true` -

- -Sets whether and where to save binding data locally to the file system. - -- If set to `true`, binding data is stored in `.wrangler/state/v3/`. It is the same as the default setting for wrangler. -- If set to `false`, binding data is not stored in file system. -- If set to `{ path: string }`, binding data is stored in the specified path. - -:::note -`wrangler`'s `--persist-to` option adds a sub directory called `v3` under the hood while the `@astrojs/cloudflare` `persist` property does not. For example, to reuse the same location as running `wrangler dev --persist-to ./my-directory`, you must specify: `persist: { path: "./my-directory/v3" }`. -::: - -The following configuration shows an example of enabling the Cloudflare runtime when running the development server, as well as using a `wrangler.json` config file. It also specifies a custom location for persisting data to the filesystem: - - -```js -import cloudflare from '@astrojs/cloudflare'; import { defineConfig } from 'astro/config'; +import cloudflare from '@astrojs/cloudflare'; -export default defineConfig({ - adapter: cloudflare({ - platformProxy: { - enabled: true, - configPath: 'wrangler.json', - persist: { - path: './.cache/wrangler/v3' - }, - }, - }), -}); -``` -### `routes.extend` - -On Cloudflare Workers, this option is not applicable. Refer to [Routing on Cloudflare Workers](#routing-on-cloudflare-workers) for more information. - -On Cloudflare Pages, this option allows you to add or exclude custom patterns (e.g. `/fonts/*`) to the generated `_routes.json` file that determines which routes are generated on-demand. This can be useful if you need to add route patterns which cannot be automatically generated, or exclude prerendered routes. - -More information about the custom route patterns can be found in [Cloudflare's routing docs](https://developers.cloudflare.com/pages/functions/routing/#functions-invocation-routes). Any routes specified are not automatically deduplicated and will be appended to the existing routes as is. - -#### `routes.extend.include` - -

-**Type:** `{ pattern: string }[]`
-**Default:** `undefined` -

- -Configures additional routes to be generated on demand by the Cloudflare adapter in the `routes.extend.include` array. - -#### `routes.extend.exclude` - -

-**Type:** `{ pattern: string }[]`
-**Default:** `undefined` -

- -Configures routes to be excluded from on-demand rendering in the `routes.extend.exclude` array. These routes will be prerendered and served statically instead, and will not invoke the server function. Additionally you can use this option to serve any static asset (e.g. images, fonts, css, js, html, txt, json, etc.) files directly without routing the request through the server function. - -```js title="astro.config.mjs" export default defineConfig({ adapter: cloudflare({ - routes: { - extend: { - include: [{ pattern: '/static' }], // Route a prerended page to the server function for on-demand rendering - exclude: [{ pattern: '/pagefind/*' }], // Use Starlight's pagefind search, which is generated statically at build time - } - }, + imageService: 'cloudflare-binding', }), }); ``` ### `sessionKVBindingName` +

-**Type:** `string`
-**Default:** `SESSION` - + **Type:** `string` +
+ **Default:** `SESSION` +

-The `sessionKVBindingName` option allows you to specify the name of the KV binding used for session storage. By default, this is set to `SESSION`, but you can change it to match your own KV binding name. See [Sessions](#sessions) for more information. +Sets the name of the KV binding used for session storage. The KV namespace is automatically provisioned when you deploy. By default, the binding is named `SESSION`, but you can change it if you define the binding manually in your wrangler config. See [Sessions](#sessions) for more information. ```js title="astro.config.mjs" "MY_SESSION_BINDING" export default defineConfig({ @@ -280,171 +166,125 @@ export default defineConfig({ }); ``` -### `workerEntryPoint` -

- -**Type:** `{ path: string | URL, namedExports: string[] }`
-**Default:** `{ path: '@astrojs/cloudflare/entrypoints/server.js', namedExports: [] }`
- -

- - -A configuration object to specify the [workerEntryPoint](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/rpc/) for your Cloudflare Worker when you use the `astro build` command. - -It allows you to optionally specify both a custom file `path` and `namedExports`: - -```js title="astro.config.mjs" -import cloudflare from '@astrojs/cloudflare'; -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - adapter: cloudflare({ - workerEntryPoint: { - path: 'src/worker.ts', - namedExports: ['MyDurableObject'] - } - }), -}); +```jsonc title="wrangler.jsonc" +{ + "kv_namespaces": [ + { + "binding": "MY_SESSION_BINDING", + } + ] +} ``` -#### `workerEntryPoint.path` +### `imagesBindingName`

- -**Type:** `string`
-**Default:** `@astrojs/cloudflare/entrypoints/server.js` - + **Type:** `string` +
+ **Default:** `IMAGES`

-The path to the entry file. This should be a relative path from the root of your Astro project. - -By default, the adapter uses a generic entry file, which only supports the `fetch` handler. +Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. The binding is automatically provisioned when you deploy. By default, the binding is named `IMAGES`, but you can change it if you define the binding manually in your wrangler config. -To support other [Cloudflare invocation handlers](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs), you can create a custom file to use as the entry point. This is useful if you want to use features that require other handlers (e.g. Durable Objects, Cloudflare Queues, Scheduled Invocations). - -#### `workerEntryPoint.namedExports` - -

- -**Type:** `[]`
-**Default:** `[]` - -

- -An array of named exports to use for the entry file. - -Provide any additional defined named exports of your [custom entry file](#creating-a-custom-cloudflare-worker-entry-file) (e.g. `DurableObject`). If not provided, only default exports will be included. - -#### Creating a custom Cloudflare Worker entry file - -The custom entry file must export the `createExports()` function with a `default` export including all the handlers you need. - -The following example entry file registers a Durable Object and a queue handler: - -```ts title="src/worker.ts" -import type { SSRManifest } from 'astro'; -import { App } from 'astro/app'; -import { handle } from '@astrojs/cloudflare/handler' -import { DurableObject } from 'cloudflare:workers'; - -class MyDurableObject extends DurableObject { - constructor(ctx: DurableObjectState, env: Env) { - super(ctx, env) - } -} +```js title="astro.config.mjs" "MY_IMAGES" +export default defineConfig({ + adapter: cloudflare({ + imageService: 'cloudflare-binding', + imagesBindingName: 'MY_IMAGES', + }), +}); +``` -export function createExports(manifest: SSRManifest) { - const app = new App(manifest); - return { - default: { - async fetch(request, env, ctx) { - await env.MY_QUEUE.send("log"); - return handle(manifest, app, request, env, ctx); - }, - async queue(batch, _env) { - let messages = JSON.stringify(batch.messages); - console.log(`consumed from our queue: ${messages}`); - } - } satisfies ExportedHandler, - MyDurableObject: MyDurableObject, - } +```jsonc title="wrangler.jsonc" +{ + "images": [ + { + "binding": "MY_IMAGES", + } + ] } -``` +``` ## Cloudflare runtime -### Usage +The Cloudflare runtime gives you access to environment variables, bindings to Cloudflare resources, and other Cloudflare-specific APIs. -The Cloudflare runtime gives you access to environment variables and bindings to Cloudflare resources defined in your `wrangler.toml`/`wrangler.jsonc` configuration file. +### Environment variables and bindings -You can access the bindings from `Astro.locals.runtime`: +Environment variables and bindings defined in your `wrangler.jsonc` configuration file are accessed by importing `env` from `cloudflare:workers`: ```astro title="src/pages/index.astro" --- -const { env } = Astro.locals.runtime; ---- -``` -You can access the runtime from API endpoints through `context.locals`: +import { env } from 'cloudflare:workers'; -```js title="src/pages/api/someFile.js" -export function GET(context) { - const runtime = context.locals.runtime; - - return new Response('Some body'); -} +const myVariable = env.MY_VARIABLE; +const myKVNamespace = env.MY_KV; +--- ``` -See the [list of all supported bindings](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings) in the Cloudflare documentation. - - -### Environment variables and secrets - -The Cloudflare runtime treats environment variables as a type of binding. - -For example, you can define an [environment variable](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc` as follows: +Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc`: ```jsonc title="wrangler.jsonc" { - "vars" : { - "MY_VARIABLE": "test" - } + "vars": { + "MY_VARIABLE": "test", + }, } ``` Secrets are a special type of environment variable that allow you to attach encrypted text values to your Worker. They need to be defined differently to ensure they are not visible after you set them. -To define `secrets`, add them through the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) rather than in your Wrangler config file. +To define `secrets`, add them through the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) rather than in your Wrangler config file: ```bash npx wrangler secret put ``` -To set secrets for local development, you also need to add a `.dev.vars` file to the root of the Astro project: +To set secrets for local development, add a `.dev.vars` file to the root of the Astro project: ```ini title=".dev.vars" DB_PASSWORD=myPassword ``` -You can then access environment variables, including secrets, from the `env` object available from `Astro.locals.runtime`: +As well as being available to import from `"cloudflare:workers"`, Cloudflare environment variables and secrets are compatible with the [`astro:env` API](/en/guides/environment-variables/#type-safe-environment-variables): + +```js +import { MY_VARIABLE } from 'astro:env/server'; +``` + +See the [list of all supported bindings](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings) in the Cloudflare documentation. + +### The `cf` object + +The Cloudflare [`cf` object](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties) contains request metadata such as geolocation information. Access it directly from the request: ```astro title="src/pages/index.astro" --- -const { env } = Astro.locals.runtime; -const myVariable = env.MY_VARIABLE; -const secret = env.DB_PASSWORD; +const cf = Astro.request.cf; +const country = cf?.country; --- ``` -Cloudflare environment variables and secrets are compatible with the [`astro:env` API](/en/guides/environment-variables/#type-safe-environment-variables). +### Execution context + +Access the Cloudflare [`ExecutionContext`](https://developers.cloudflare.com/workers/runtime-apis/context/) through `Astro.locals.cfContext`. This is useful for operations like [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil), or accessing [Durable Object exports](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) within your page. + +```astro title="src/pages/index.astro" +--- +const cfContext = Astro.locals.cfContext; +cfContext.exports.Greeter.greet('Astro'); +cfContext.waitUntil(someAsyncOperation()); +--- +``` ### Typing -`wrangler` provides a `types` command to generate TypeScript types for the bindings. This allows you to type locals without the need to manually type them. Refer to the [Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/commands/#types) for more information. +`wrangler` provides a `types` command to generate TypeScript types for your bindings. This allows you to type your environment without the need for manual type definitions. Refer to the [Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/commands/#types) for more information. -Every time you change your configuration files (e.g. `wrangler.toml`, `.dev.vars`) you need to run `wrangler types`. +Run `wrangler types` every time you change your configuration files (e.g. `wrangler.jsonc`, `.dev.vars`). :::note -You can create a pnpm script to run `wrangler types` automatically before other commands. +The following example shows a script configuration to run `wrangler types` automatically before other commands: ```json title="package.json" { @@ -457,117 +297,48 @@ You can create a pnpm script to run `wrangler types` automatically before other } } ``` -::: -You can type the `runtime` object by [extending global types](/en/guides/typescript/#extending-global-types) using `Runtime`: - -```ts title="src/env.d.ts" -type Runtime = import('@astrojs/cloudflare').Runtime; - -declare namespace App { - interface Locals extends Runtime { - otherLocals: { - test: string; - }; - } -} -``` +::: ## Cloudflare Platform ### Headers -You can attach [custom headers](https://developers.cloudflare.com/pages/platform/headers/) to your responses by adding a `_headers` file in your Astro project's `public/` folder. This file will be copied to your build output directory. - -This is available on Cloudflare Workers and Pages. +Add [custom headers](https://developers.cloudflare.com/workers/static-assets/headers/) to your responses by creating a `_headers` file in your Astro project's `public/` folder. This file will be copied to the build output directory. ### Assets + Assets built by Astro are all named with a hash and therefore can be given long cache headers. By default, Astro on Cloudflare will add such a header for these files. ### Redirects -You can declare [custom redirects](https://developers.cloudflare.com/pages/platform/redirects/) to redirect requests to a different URL. To do so, add a `_redirects` file in your Astro project's `public/` folder. This file will be copied to your build output directory. - -This is available on Cloudflare Workers and Pages. +Declare [custom redirects](https://developers.cloudflare.com/workers/static-assets/redirects/) by adding a `_redirects` file in your Astro project's `public/` folder. This file will be copied to your build output directory. This only applies to static assets; dynamic routes should use [Astro redirects](/en/guides/routing/#configured-redirects). ### Routes -#### Routing on Cloudflare Workers Routing for static assets is based on the file structure in the build directory (e.g. `./dist`). If no match is found, this will fall back to the Worker for on-demand rendering. Read more about [static asset routing with Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/routing/). -Unlike [Cloudflare Pages](#routing-on-cloudflare-pages), with Workers, you do not need a `_routes.json` file. - -Currently, the Cloudflare adapter always generates this file. To work around this, create a `.assetsignore` file in your `public/` folder, and add the following lines to it: - ```txt title="public/.assetsignore" - _worker.js - _routes.json - ``` - -#### Routing on Cloudflare Pages - -For Cloudflare Pages, [routing](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes) uses a `_routes.json` file to determine which requests are routed to the server function and which are served as static assets. By default, a `_routes.json` file will be automatically generated for your project based on its files and configuration. - -You can [specify additional routing patterns to follow](#routesextend) in your adapter config, or create your own custom `_routes.json` file to fully override the automatic generation. - - -Creating a custom `public/_routes.json` will override the automatic generation. See [Cloudflare's documentation on creating a custom `_routes.json`](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file) for more details. - ## Sessions -The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices. +The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices. -Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. Before using sessions, you need to create a KV namespace to store the data and configure a KV binding in your Wrangler config file. By default, Astro expects the KV binding to be named `SESSION`, but you can choose a different name if you prefer by setting the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config. - - +Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. The KV namespace is [automatically provisioned](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning) when you deploy, so no manual setup is required. Alternatively, you can define the KV binding manually in your `wrangler.jsonc` file and set a custom binding name using the [`sessionKVBindingName`](#sessionkvbindingname) adapter option. -1. Create a KV namespace using the Wrangler CLI and make note of the ID of the new namespace: - - ```sh - npx wrangler kv namespace create "SESSION" - ``` +```astro title="src/components/CartButton.astro" +--- +export const prerender = false; +const cart = await Astro.session?.get('cart'); +--- -2. Declare the KV namespace in your Wrangler config, setting the namespace ID to the one returned by the previous command: - - - - ```json title="wrangler.jsonc" "" - { - "kv_namespaces": [ - { - "binding": "SESSION", - "id": "" - } - ] - } - ``` - - - ```toml title="wrangler.toml" "" - kv_namespaces = [ - { binding = "SESSION", id = "" } - ] - ``` - - - -3. You can then use sessions in your server code: - - ```astro title="src/components/CartButton.astro" "Astro.session?.get('cart')" - --- - export const prerender = false; - const cart = await Astro.session?.get('cart'); - --- - - 🛒 {cart?.length ?? 0} items - ``` +🛒 {cart?.length ?? 0} items +``` - +By default, the KV binding is named `SESSION`. To use a different name, set the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config. :::note Writes to Cloudflare KV are [eventually consistent](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency) between regions. This means that changes are available immediately within the same region but may take up to 60 seconds to propagate globally. This won't affect most users as they are unlikely to switch regions between requests, but it may be a consideration for some use cases, such as VPN users. ::: - ## Cloudflare Module Imports The Cloudflare `workerd` runtime supports imports of some [non-standard module types](https://developers.cloudflare.com/workers/wrangler/bundling/#including-non-javascript-modules). Most additional file types are also available in Astro: @@ -598,68 +369,247 @@ While this example is trivial, Wasm can be used to accelerate computationally in ## Node.js compatibility -Out of the box, Cloudflare does not support the Node.js runtime APIs. With some configuration, Cloudflare does support a subset of the Node.js runtime APIs. You can find supported Node.js runtime APIs in Cloudflare's [documentation](https://developers.cloudflare.com/workers/runtime-apis/nodejs). +Cloudflare Workers supports a growing subset of Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. -To use these APIs, your page or endpoint must be server-side rendered (not pre-rendered) and must use the `import {} from 'node:*'` import syntax. +To enable Node.js compatibility, add the `nodejs_compat` flag to your Wrangler configuration: -```js title="pages/api/endpoint.js" +```jsonc title="wrangler.jsonc" +{ + "compatibility_flags": ["nodejs_compat"], +} +``` + +Then use the `node:*` import syntax in your server-side code: + +```js title="src/pages/api/endpoint.js" export const prerender = false; import { Buffer } from 'node:buffer'; ``` -You'll also need to modify the `vite` configuration in your Astro config to allow for the `node:*` import syntax: +For APIs not yet natively supported, Wrangler automatically provides polyfills. -```js title="astro.config.mjs" ins={6-10} -import {defineConfig} from "astro/config"; -import cloudflare from '@astrojs/cloudflare'; +See the [Cloudflare documentation on Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) for the complete list of supported APIs and configuration details. + +## Local preview + +After building your project with `astro build`, use `astro preview` to test your Cloudflare Workers application locally. The preview runs using Cloudflare's `workerd` runtime, providing a staging environment that matches production exactly. +### Meaningful error messages + +Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: + +```js title="astro.config.mjs" ins={3-7} export default defineConfig({ - adapter: cloudflare({}), + adapter: cloudflare(), vite: { - ssr: { - external: ['node:buffer'], - }, - }, -}) + build: { + minify: false, + }, + }, +}); ``` -Additionally, you'll need to follow Cloudflare's documentation on how to enable support. For detailed guidance, please refer to the [Cloudflare documentation on enabling Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). +## Using with Cloudflare Pages + +The Cloudflare adapter deploys to Cloudflare Workers by default. To deploy to Cloudflare Pages instead, additional manual configuration is required. -:::note[Package Compatibility Implications] -If a project imports a package into the server that uses the Node.js runtime APIs, this can cause issues when deploying to Cloudflare. This issue arises with package that do not use the `node:*` import syntax. It is recommended that you contact the authors of the package to determine if the package supports the above import syntax. If the package does not support this, you may need to use a different package. +:::caution +Cloudflare recommends migrating from Pages to Workers for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information. ::: -## Preview with Wrangler + +1. Configure your build output directories in `astro.config.mjs`: + + ```js title="astro.config.mjs" ins={6-9} + import { defineConfig } from 'astro/config'; + import cloudflare from '@astrojs/cloudflare'; + + export default defineConfig({ + adapter: cloudflare(), + build: { + client: './dist', + server: './dist/_worker.js', + }, + }); + ``` + +2. Create a `_routes.json` file in your `public/` folder to route requests to your Worker: -To use [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) to run your application locally, update the preview script. + ```jsonc title="public/_routes.json" + { + "version": 1, + "include": ["/*"], // Alternatively, specify specific routes + "exclude": ["/static/*"] // Exclude static assets if needed + } + ``` -For Workers: + See the [Cloudflare documentation on routing with Pages](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) for more details. + -```json title="package.json" -"preview": "wrangler dev" +## Upgrading to Astro 6 + +Astro 6 brings significant improvements to the Cloudflare development experience and requires `@astrojs/cloudflare` v13 or later. Now, `astro dev` uses Cloudflare's Vite plugin and `workerd` runtime to closely mirror production behavior. + + + See [the Astro 6 upgrade guide](/en/guides/upgrade-to/v6/) for full instructions on upgrading + Astro itself. + + +### Development server now uses workerd + +The biggest change for Cloudflare users in Astro 6 is that `astro dev` and `astro preview` now use the Cloudflare Vite plugin to run your site using the real Workers runtime (`workerd`) instead of Node.js. This means your development environment is now a much closer replica of your production environment, with the same runtime, APIs, and behavior. + +This change helps you catch issues during development that would have previously only appeared in production, and features like Durable Objects, R2 bindings, and Workers AI now work exactly as they do when deployed to Cloudflare's platform. + +This change is transparent for most projects. If your project had special configuration for `astro dev` or was relying on Node.js-specific behavior in development, adjust your code or configuration accordingly. + +### Changed: Wrangler entrypoint configuration + +Previously, the `main` field in your Wrangler configuration pointed to the built worker file (e.g. `dist/_worker.js/index.js`). With Astro 6, this has changed to point to a new unified entrypoint provided by the Cloudflare adapter: `@astrojs/cloudflare/entrypoints/server`. + +Update your `wrangler.jsonc` to use the new entrypoint: + +```jsonc title="wrangler.jsonc" del={2} ins={3} +{ + "main": "dist/_worker.js/index.js", + "main": "@astrojs/cloudflare/entrypoints/server", + "name": "my-astro-app", + // ... rest of config +} ``` -For Pages: +This single entrypoint handles both `astro dev` and production deployments. -```json title="package.json" -"preview": "wrangler pages dev ./dist" +### Removed: `Astro.locals.runtime` API + +The `Astro.locals.runtime` object has been removed in favor of direct access to Cloudflare Workers APIs. Access environment variables, the `cf` object, caches, and execution context directly through the provided interfaces. + +**Accessing environment variables:** + +Previously, environment variables were accessed through `Astro.locals.runtime.env`. Now import `env` directly instead: + +```js del={1} ins={2} +const { env } = Astro.locals.runtime; +import { env } from 'cloudflare:workers'; ``` -Developing with [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) gives you access to [Cloudflare bindings](https://developers.cloudflare.com/pages/platform/functions/bindings), [environment variables](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), and the [cf object](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties). Getting hot reloading of the Astro dev server to work with Wrangler might require custom setup. See [community examples](https://github.com/withastro/roadmap/discussions/590). +**Accessing the `cf` object:** -### Meaningful error messages +Previously, the `cf` object was accessed through `Astro.locals.runtime.cf`. Now access it directly from the request: -Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, you can add `vite.build.minify = false` setting to your `astro.config.mjs`. +```js del={1} ins={2} +const { cf } = Astro.locals.runtime; +const cf = Astro.request.cf; +``` -```js title="astro.config.mjs" ins={3-7} -export default defineConfig({ - adapter: cloudflare(), - vite: { - build: { - minify: false, - }, +**Accessing the caches API:** + +Previously, the caches API was accessed through `Astro.locals.runtime.caches`. Now use the global `caches` object directly: + +```js del={1} +const { caches } = Astro.locals.runtime; + +caches.default.put(request, response); +``` + +**Accessing the execution context:** + +The `Astro.locals.runtime.ctx` object is replaced with `Astro.locals.cfContext` which contains the Cloudflare `ExecutionContext`: + +```js del={1} ins={2} +const ctx = Astro.locals.runtime.ctx; +const ctx = Astro.locals.cfContext; +``` + +### Optional: Wrangler configuration file + +The Wrangler configuration file is now optional for simple projects. If you don't have custom configuration such as Cloudflare bindings (KV, D1, Durable Objects, etc.), Astro will automatically generate a default configuration for you. + +If your `wrangler.jsonc` only contains basic configuration like this: + +```jsonc +{ + "main": "@astrojs/cloudflare/entrypoints/server", + "compatibility_date": "2025-05-21", + "assets": { + "directory": "./dist", + "binding": "ASSETS", }, -}); +} +``` + +You can safely delete this file. Astro handles this configuration automatically. Alternatively, create a minimal `wrangler.jsonc` with just your project name and other custom settings: + +```jsonc title="wrangler.jsonc" +{ + "name": "my-astro-app", +} ``` +### Changed: Custom entrypoint API + +If you were using a custom `workerEntryPoint` configuration in the adapter options, this has been removed. Instead, specify your custom entrypoint in your Wrangler configuration and create a standard Cloudflare Worker export object directly, rather than using the `createExports()` function. + + +1. Remove the `workerEntryPoint` option from your adapter config: + + ```js title="astro.config.mjs" del={6-9} + import { defineConfig } from 'astro/config'; + import cloudflare from '@astrojs/cloudflare'; + + export default defineConfig({ + adapter: cloudflare({ + workerEntryPoint: { + path: 'src/worker.ts', + namedExports: ['MyDurableObject'], + }, + }), + }); + ``` + +2. Specify the entrypoint in `wrangler.jsonc` instead: + + ```jsonc title="wrangler.jsonc" + { + "main": "./src/worker.ts" + } + ``` + +3. Update your custom worker entry file to use standard Worker syntax. Import the handler from `@astrojs/cloudflare/entrypoints/server` and export a standard Cloudflare Worker object, alongside any custom exports like Durable Objects: + + ```ts title="src/worker.ts" + import handler from '@astrojs/cloudflare/entrypoints/server'; + import { DurableObject } from 'cloudflare:workers'; + + export class MyDurableObject extends DurableObject { + // ... + } + + export default { + async fetch(request, env, ctx) { + await env.MY_QUEUE.send('log'); + return handler.fetch(request, env, ctx); + }, + async queue(batch, _env) { + let messages = JSON.stringify(batch.messages); + console.log(`consumed from our queue: ${messages}`); + }, + } satisfies ExportedHandler; + ``` + + +The manifest is now created internally by the adapter, so does not need to be passed to your handler. + +### New: `astro preview` support + +Use `astro preview` to test your Cloudflare Workers application locally before deploying. The preview runs using Cloudflare's `workerd` runtime, providing a staging environment that matches production exactly. Run `astro build` followed by `astro preview` to start the preview server. + +### Deprecated: Cloudflare Pages support + +The Astro Cloudflare adapter now only supports deploying to Cloudflare Workers by default. If you are currently deploying to Cloudflare Pages, consider migrating to Workers for the best experience and feature support. + +See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for detailed migration instructions. + +If you need to continue using Cloudflare Pages, see [Using with Cloudflare Pages](#using-with-cloudflare-pages) for the required manual configuration. + [astro-integration]: /en/guides/integrations-guide/ diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 3bf12d30098c5..e73ecb468c997 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -168,13 +168,15 @@ import { z } from 'astro/zod'; All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters) have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler. -In particular, Astro's Cloudflare adapter has undergone significant changes, and breaking changes to your existing Cloudflare setup are expected. +In particular, Astro's Cloudflare adapter has undergone significant changes, and breaking changes to your existing Cloudflare setup are expected. + +See the [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-astro-6) for detailed migration guidance. #### What should I do? If you are using an Astro adapter for on-demand rendering or other platform-specific features, please check your specific adapter's changelog for upgrade guidance: -- [`@astrojs/cloudflare` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/cloudflare/CHANGELOG.md) +- [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-astro-6) - [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/netlify/CHANGELOG.md) - [`@astrojs/node` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/node/CHANGELOG.md) - [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/vercel/CHANGELOG.md) From 658f47706481c952e4c76e09859e3c1b92562f98 Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Wed, 14 Jan 2026 12:00:23 +0000 Subject: [PATCH 2/6] Changes from review --- .../guides/integrations-guide/cloudflare.mdx | 65 +++++++++---------- 1 file changed, 31 insertions(+), 34 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 2e5354ea5afb0..e26c3bcaacbbd 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -90,7 +90,7 @@ Now, you can enable [on-demand rendering per page](/en/guides/on-demand-renderin }); ``` -3. Optionally, create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings, or to declare Cloudflare bindings (KV, D1, Durable Objects, etc.): +3. Astro will automatically generate a default configuration, using the package.json name field or the folder name as Worker name. You can optionally create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings. This example declares Cloudflare KV bindings: ```jsonc title="wrangler.jsonc" { @@ -99,9 +99,6 @@ Now, you can enable [on-demand rendering per page](/en/guides/on-demand-renderin // "kv_namespaces": [{ "binding": "MY_KV", "id": "" }] } ``` - - For simple projects without bindings, you can skip this step as Astro will generate a default configuration automatically. The Worker name will be based on the `package.json` name field or the folder name. - ## Options @@ -111,9 +108,8 @@ The Cloudflare adapter accepts the following options: ### `cloudflareModules`

- **Type:** `boolean` -
- **Default:** `true` +**Type:** `boolean`
+**Default:** `true`

Enables [imports of `.wasm`, `.bin`, and `.txt` modules](#cloudflare-module-imports). @@ -123,9 +119,8 @@ This functionality is enabled by default. If you'd like to disable, set `cloudfl ### `imageService`

- **Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom'` -
- **Default:** `'compile'` +**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom'`
+**Default:** `'compile'`

Determines which image service is used by the adapter. The adapter will default to `compile` mode when an incompatible image service is configured. Otherwise, it will use the globally configured image service: @@ -150,13 +145,12 @@ export default defineConfig({ ### `sessionKVBindingName`

- **Type:** `string` -
- **Default:** `SESSION` - +**Type:** `string`
+**Default:** `SESSION` +

-Sets the name of the KV binding used for session storage. The KV namespace is automatically provisioned when you deploy. By default, the binding is named `SESSION`, but you can change it if you define the binding manually in your wrangler config. See [Sessions](#sessions) for more information. +Sets the name of the KV binding used for session storage. By default, rhe KV namespace is automatically provisioned when you deploy, and is named `SESSION`. You can change this name by setting the binding manually in your wrangler config. See [Sessions](#sessions) for more information. ```js title="astro.config.mjs" "MY_SESSION_BINDING" export default defineConfig({ @@ -179,12 +173,11 @@ export default defineConfig({ ### `imagesBindingName`

- **Type:** `string` -
- **Default:** `IMAGES` +**Type:** `string`
+**Default:** `IMAGES`

-Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. The binding is automatically provisioned when you deploy. By default, the binding is named `IMAGES`, but you can change it if you define the binding manually in your wrangler config. +Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. By default, the binding is automatically provisioned when you deploy and the binding is named `IMAGES`. You can change it by setting the binding manually in your wrangler config: ```js title="astro.config.mjs" "MY_IMAGES" export default defineConfig({ @@ -211,16 +204,9 @@ The Cloudflare runtime gives you access to environment variables, bindings to Cl ### Environment variables and bindings -Environment variables and bindings defined in your `wrangler.jsonc` configuration file are accessed by importing `env` from `cloudflare:workers`: +Environment variables and bindings defined in your `wrangler.jsonc` configuration file. -```astro title="src/pages/index.astro" ---- -import { env } from 'cloudflare:workers'; -const myVariable = env.MY_VARIABLE; -const myKVNamespace = env.MY_KV; ---- -``` Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc`: @@ -246,7 +232,18 @@ To set secrets for local development, add a `.dev.vars` file to the root of the DB_PASSWORD=myPassword ``` -As well as being available to import from `"cloudflare:workers"`, Cloudflare environment variables and secrets are compatible with the [`astro:env` API](/en/guides/environment-variables/#type-safe-environment-variables): +Cloudflare environment variables and secrets can be imported from `"cloudflare:workers"`: + +```astro title="src/pages/index.astro" +--- +import { env } from 'cloudflare:workers'; + +const myVariable = env.MY_VARIABLE; +const myKVNamespace = env.MY_KV; +--- +``` + +They are also compatible with the [`astro:env` API](/en/guides/environment-variables/#type-safe-environment-variables): ```js import { MY_VARIABLE } from 'astro:env/server'; @@ -326,7 +323,7 @@ Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv ```astro title="src/components/CartButton.astro" --- -export const prerender = false; +export const prerender = false; // Not needed in 'server' mode const cart = await Astro.session?.get('cart'); --- @@ -369,7 +366,7 @@ While this example is trivial, Wasm can be used to accelerate computationally in ## Node.js compatibility -Cloudflare Workers supports a growing subset of Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. +Cloudflare Workers support most Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. To enable Node.js compatibility, add the `nodejs_compat` flag to your Wrangler configuration: @@ -382,7 +379,7 @@ To enable Node.js compatibility, add the `nodejs_compat` flag to your Wrangler c Then use the `node:*` import syntax in your server-side code: ```js title="src/pages/api/endpoint.js" -export const prerender = false; +export const prerender = false; // Not needed in 'server' mode import { Buffer } from 'node:buffer'; ``` @@ -396,7 +393,7 @@ After building your project with `astro build`, use `astro preview` to test your ### Meaningful error messages -Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: +By default, errors occurring while running your application in Wrangler are minified. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: ```js title="astro.config.mjs" ins={3-7} export default defineConfig({ @@ -427,8 +424,8 @@ Cloudflare recommends migrating from Pages to Workers for new projects. See Clou export default defineConfig({ adapter: cloudflare(), build: { - client: './dist', - server: './dist/_worker.js', + client: './', + server: './_worker.js', }, }); ``` From 65758abb0ec6835254faf23ae543da7fcc9a785f Mon Sep 17 00:00:00 2001 From: Matt Kane Date: Wed, 14 Jan 2026 12:54:16 +0000 Subject: [PATCH 3/6] More rewording --- .../guides/integrations-guide/cloudflare.mdx | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index e26c3bcaacbbd..8bcf9e034284f 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -190,11 +190,9 @@ export default defineConfig({ ```jsonc title="wrangler.jsonc" { - "images": [ - { - "binding": "MY_IMAGES", - } - ] + "images": { + "binding": "MY_IMAGES" + } } ``` @@ -204,7 +202,7 @@ The Cloudflare runtime gives you access to environment variables, bindings to Cl ### Environment variables and bindings -Environment variables and bindings defined in your `wrangler.jsonc` configuration file. +Environment variables and bindings are defined in your `wrangler.jsonc` configuration file. @@ -264,7 +262,7 @@ const country = cf?.country; ### Execution context -Access the Cloudflare [`ExecutionContext`](https://developers.cloudflare.com/workers/runtime-apis/context/) through `Astro.locals.cfContext`. This is useful for operations like [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil), or accessing [Durable Object exports](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) within your page. +Access the Cloudflare [`ExecutionContext`](https://developers.cloudflare.com/workers/runtime-apis/context/) through `Astro.locals.cfContext`. This is useful for operations like [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil), or accessing [Durable Object exports](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) within your page. ```astro title="src/pages/index.astro" --- @@ -301,7 +299,7 @@ The following example shows a script configuration to run `wrangler types` autom ### Headers -Add [custom headers](https://developers.cloudflare.com/workers/static-assets/headers/) to your responses by creating a `_headers` file in your Astro project's `public/` folder. This file will be copied to the build output directory. +Add [custom headers](https://developers.cloudflare.com/workers/static-assets/headers/) for static assets by creating a `_headers` file in your Astro project's `public/` folder. This file will be copied to the build output directory. Headers in `_headers` are not applied to responses generated by your Worker code. ### Assets @@ -319,7 +317,7 @@ Routing for static assets is based on the file structure in the build directory The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices. -Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. The KV namespace is [automatically provisioned](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning) when you deploy, so no manual setup is required. Alternatively, you can define the KV binding manually in your `wrangler.jsonc` file and set a custom binding name using the [`sessionKVBindingName`](#sessionkvbindingname) adapter option. +Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. Wrangler can [automatically provision](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning) the KV namespace when you deploy, so no manual setup is required. Alternatively, you can define the KV binding manually in your `wrangler.jsonc` file and set a custom binding name using the [`sessionKVBindingName`](#sessionkvbindingname) adapter option. ```astro title="src/components/CartButton.astro" --- @@ -383,13 +381,13 @@ export const prerender = false; // Not needed in 'server' mode import { Buffer } from 'node:buffer'; ``` -For APIs not yet natively supported, Wrangler automatically provides polyfills. +For Node.js APIs not yet supported in the Workers runtime, Wrangler can inject polyfills (requires `nodejs_compat` and a compatibility date of 2024-09-23 or later). See the [Cloudflare documentation on Node.js compatibility](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) for the complete list of supported APIs and configuration details. ## Local preview -After building your project with `astro build`, use `astro preview` to test your Cloudflare Workers application locally. The preview runs using Cloudflare's `workerd` runtime, providing a staging environment that matches production exactly. +After building your project with `astro build`, use `astro preview` to test your Cloudflare Workers application locally. The preview runs using Cloudflare's `workerd` runtime, closely mirroring production behavior. ### Meaningful error messages @@ -411,7 +409,7 @@ export default defineConfig({ The Cloudflare adapter deploys to Cloudflare Workers by default. To deploy to Cloudflare Pages instead, additional manual configuration is required. :::caution -Cloudflare recommends migrating from Pages to Workers for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information. +Cloudflare recommends using Workers, rather than Pages for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information. ::: @@ -599,7 +597,7 @@ The manifest is now created internally by the adapter, so does not need to be pa ### New: `astro preview` support -Use `astro preview` to test your Cloudflare Workers application locally before deploying. The preview runs using Cloudflare's `workerd` runtime, providing a staging environment that matches production exactly. Run `astro build` followed by `astro preview` to start the preview server. +Use `astro preview` to test your Cloudflare Workers application locally before deploying. The preview runs using Cloudflare's `workerd` runtime, closely mirroring production behavior. Run `astro build` followed by `astro preview` to start the preview server. ### Deprecated: Cloudflare Pages support From 3069fdfb52f08ccba2ad821cedf66951470ec3d1 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 14 Jan 2026 11:02:21 -0400 Subject: [PATCH 4/6] Yan review Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../guides/integrations-guide/cloudflare.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 8bcf9e034284f..f30643df2d4ee 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -90,7 +90,7 @@ Now, you can enable [on-demand rendering per page](/en/guides/on-demand-renderin }); ``` -3. Astro will automatically generate a default configuration, using the package.json name field or the folder name as Worker name. You can optionally create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings. This example declares Cloudflare KV bindings: +3. Astro will automatically generate a default configuration, using the package.json name field or the folder name as the Worker name. You can optionally create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings. This example declares Cloudflare KV bindings: ```jsonc title="wrangler.jsonc" { @@ -128,7 +128,7 @@ Determines which image service is used by the adapter. The adapter will default - **`cloudflare`:** Uses the [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) service. - **`cloudflare-binding`:** Uses the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) for image transformation. The binding is automatically provisioned when you deploy. - **`passthrough`:** Uses the existing [`noop`](/en/guides/images/#configure-no-op-passthrough-service) service. -- **`compile`:** Uses Astro's default service (sharp), but only on pre-rendered routes at build time. For pages rendered on-demand, all `astro:assets` features are disabled. +- **`compile`:** Uses Astro's default service (sharp), but only on pre-rendered routes at build time. For pages rendered on demand, all `astro:assets` features are disabled. - **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options). **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.** ```js title="astro.config.mjs" ins={6} @@ -150,7 +150,7 @@ export default defineConfig({

-Sets the name of the KV binding used for session storage. By default, rhe KV namespace is automatically provisioned when you deploy, and is named `SESSION`. You can change this name by setting the binding manually in your wrangler config. See [Sessions](#sessions) for more information. +Sets the name of the KV binding used for session storage. By default, the KV namespace is automatically provisioned when you deploy, and is named `SESSION`. You can change this name by setting the binding manually in your wrangler config. See [Sessions](#sessions) for more information. ```js title="astro.config.mjs" "MY_SESSION_BINDING" export default defineConfig({ @@ -177,7 +177,7 @@ export default defineConfig({ **Default:** `IMAGES`

-Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. By default, the binding is automatically provisioned when you deploy and the binding is named `IMAGES`. You can change it by setting the binding manually in your wrangler config: +Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. By default, the binding is automatically provisioned with the name `IMAGES` when you deploy. You can change it by setting the binding manually in your wrangler config: ```js title="astro.config.mjs" "MY_IMAGES" export default defineConfig({ @@ -303,7 +303,7 @@ Add [custom headers](https://developers.cloudflare.com/workers/static-assets/hea ### Assets -Assets built by Astro are all named with a hash and therefore can be given long cache headers. By default, Astro on Cloudflare will add such a header for these files. +Assets built by Astro are all named with a hash and, therefore, can be given long cache headers. By default, Astro on Cloudflare will add such a header for these files. ### Redirects @@ -409,7 +409,7 @@ export default defineConfig({ The Cloudflare adapter deploys to Cloudflare Workers by default. To deploy to Cloudflare Pages instead, additional manual configuration is required. :::caution -Cloudflare recommends using Workers, rather than Pages for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information. +Cloudflare recommends using Workers for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information if you have an existing project using Pages. ::: @@ -509,7 +509,7 @@ caches.default.put(request, response); **Accessing the execution context:** -The `Astro.locals.runtime.ctx` object is replaced with `Astro.locals.cfContext` which contains the Cloudflare `ExecutionContext`: +The `Astro.locals.runtime.ctx` object is replaced with `Astro.locals.cfContext`, which contains the Cloudflare `ExecutionContext`: ```js del={1} ins={2} const ctx = Astro.locals.runtime.ctx; @@ -518,7 +518,7 @@ const ctx = Astro.locals.cfContext; ### Optional: Wrangler configuration file -The Wrangler configuration file is now optional for simple projects. If you don't have custom configuration such as Cloudflare bindings (KV, D1, Durable Objects, etc.), Astro will automatically generate a default configuration for you. +The Wrangler configuration file is now optional for simple projects. If you don't have custom configuration, such as Cloudflare bindings (KV, D1, Durable Objects, etc.), Astro will automatically generate a default configuration for you. If your `wrangler.jsonc` only contains basic configuration like this: @@ -593,7 +593,7 @@ If you were using a custom `workerEntryPoint` configuration in the adapter optio ``` -The manifest is now created internally by the adapter, so does not need to be passed to your handler. +The manifest is now created internally by the adapter, so it does not need to be passed to your handler. ### New: `astro preview` support From 8a4745ccbf3330ad09449851c1bb2dc8da5b9fbc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:04:48 -0400 Subject: [PATCH 5/6] Sarah polishing pass --- .../guides/integrations-guide/cloudflare.mdx | 28 ++++++++----------- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 2 files changed, 13 insertions(+), 17 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index f30643df2d4ee..b19bd21613d09 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -12,7 +12,7 @@ i18nReady: true import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import ReadMore from '~/components/ReadMore.astro'; import Since from '~/components/Since.astro'; -import { Tabs, TabItem, Steps, Aside } from '@astrojs/starlight/components'; +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Cloudflare](https://www.cloudflare.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/). @@ -20,10 +20,9 @@ If you're using Astro as a static site builder, you don't need an adapter. Learn how to deploy your Astro site in our [Cloudflare deployment guide](/en/guides/deploy/cloudflare/). - +:::tip[Upgrading to Astro 6?] +Astro 6 requires an upgrade to v13 of this adapter. See the [Cloudflare adapter upgrade instructions for Astro 6](#upgrading-to-v13-and-astro-6) for breaking changes and migration guidance. +::: ## Why Astro Cloudflare @@ -128,7 +127,7 @@ Determines which image service is used by the adapter. The adapter will default - **`cloudflare`:** Uses the [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) service. - **`cloudflare-binding`:** Uses the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) for image transformation. The binding is automatically provisioned when you deploy. - **`passthrough`:** Uses the existing [`noop`](/en/guides/images/#configure-no-op-passthrough-service) service. -- **`compile`:** Uses Astro's default service (sharp), but only on pre-rendered routes at build time. For pages rendered on demand, all `astro:assets` features are disabled. +- **`compile`:** Uses Astro's default service (Sharp), but only on pre-rendered routes at build time. For pages rendered on demand, all `astro:assets` features are disabled. - **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options). **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.** ```js title="astro.config.mjs" ins={6} @@ -206,7 +205,7 @@ Environment variables and bindings are defined in your `wrangler.jsonc` configur -Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc`: +Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) that do not store sensitive information in `wrangler.jsonc`: ```jsonc title="wrangler.jsonc" { @@ -216,7 +215,7 @@ Define [environment variables](https://developers.cloudflare.com/workers/configu } ``` -Secrets are a special type of environment variable that allow you to attach encrypted text values to your Worker. They need to be defined differently to ensure they are not visible after you set them. +[Secrets](https://developers.cloudflare.com/workers/configuration/secrets/) are a special type of environment variable that allow you to attach encrypted text values to your Worker. They need to be defined differently to ensure they are not visible within Wrangler or Cloudflare dashboard after you set them. To define `secrets`, add them through the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) rather than in your Wrangler config file: @@ -274,7 +273,7 @@ cfContext.waitUntil(someAsyncOperation()); ### Typing -`wrangler` provides a `types` command to generate TypeScript types for your bindings. This allows you to type your environment without the need for manual type definitions. Refer to the [Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/commands/#types) for more information. +`wrangler` provides a [`types`](https://developers.cloudflare.com/workers/wrangler/commands/#types) command to generate TypeScript types for your bindings. This allows you to type your environment without the need for manual type definitions. Run `wrangler types` every time you change your configuration files (e.g. `wrangler.jsonc`, `.dev.vars`). @@ -307,7 +306,7 @@ Assets built by Astro are all named with a hash and, therefore, can be given lon ### Redirects -Declare [custom redirects](https://developers.cloudflare.com/workers/static-assets/redirects/) by adding a `_redirects` file in your Astro project's `public/` folder. This file will be copied to your build output directory. This only applies to static assets; dynamic routes should use [Astro redirects](/en/guides/routing/#configured-redirects). +Declare [custom redirects for static assets](https://developers.cloudflare.com/workers/static-assets/redirects/) by adding a `_redirects` file in your Astro project's `public/` folder. This file will be copied to your build output directory. For dynamic routes, [configure redirects in Astro directly](/en/guides/routing/#configured-redirects) instead. ### Routes @@ -441,14 +440,11 @@ Cloudflare recommends using Workers for new projects. See Cloudflare's [migratio See the [Cloudflare documentation on routing with Pages](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) for more details. -## Upgrading to Astro 6 +## Upgrading to v13 and Astro 6 Astro 6 brings significant improvements to the Cloudflare development experience and requires `@astrojs/cloudflare` v13 or later. Now, `astro dev` uses Cloudflare's Vite plugin and `workerd` runtime to closely mirror production behavior. - - See [the Astro 6 upgrade guide](/en/guides/upgrade-to/v6/) for full instructions on upgrading - Astro itself. - +See [the Astro 6 upgrade guide](/en/guides/upgrade-to/v6/) for full instructions on upgrading Astro itself. ### Development server now uses workerd @@ -516,7 +512,7 @@ const ctx = Astro.locals.runtime.ctx; const ctx = Astro.locals.cfContext; ``` -### Optional: Wrangler configuration file +### Changed: Wrangler configuration file is now optional The Wrangler configuration file is now optional for simple projects. If you don't have custom configuration, such as Cloudflare bindings (KV, D1, Durable Objects, etc.), Astro will automatically generate a default configuration for you. diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index be0fa2783a842..fe7da7ff02123 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -176,7 +176,7 @@ In particular, Astro's Cloudflare adapter has undergone significant changes, and If you are using an Astro adapter for on-demand rendering or other platform-specific features, please check your specific adapter's changelog for upgrade guidance: -- [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-astro-6) +- [`@astrojs/cloudflare` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/cloudflare/CHANGELOG.md) - [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/netlify/CHANGELOG.md) - [`@astrojs/node` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/node/CHANGELOG.md) - [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/vercel/CHANGELOG.md) From 82b082ff73beb85ee671ad5c2eda6ea4d1fa376b Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 14 Jan 2026 12:13:30 -0400 Subject: [PATCH 6/6] fix link --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index fe7da7ff02123..fd6d6446b4e73 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -170,7 +170,7 @@ All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server In particular, Astro's Cloudflare adapter has undergone significant changes, and breaking changes to your existing Cloudflare setup are expected. -See the [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-astro-6) for detailed migration guidance. +See the [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-v13-and-astro-6) for detailed migration guidance. #### What should I do?