#16435 c4d321b Thanks @jamesopstad! - Add support for Preview deployments (currently in private beta)
Non-inheritable bindings set internally by the Cloudflare adapter are now also set in the previews section of the config so that they are inherited by Preview deployments.
#16320 a43eb4b Thanks @matthewp! - Uses redirect: 'manual' for remote image fetches in the Cloudflare binding image transform, consistent with all other image fetch paths
#16307 a81dd3e Thanks @matthewp! - Surfaces console.log and console.warn output from workerd during prerendering
Updated dependencies []:
#16225 756e7be Thanks @travisbreaks! - Fixes ERR_MULTIPLE_CONSUMERS error when using Cloudflare Queues with prerendered pages. The prerender worker config callback now excludes queues.consumers from the entry worker config, since the prerender worker only renders static HTML and should not register as a queue consumer. Queue producers (bindings) are preserved.
#16192 79d86b8 Thanks @alexanderniebuhr! - Removes an unused function re-export from the /info package path
Updated dependencies []:
814406d]:
#16041 56d2bde Thanks @kylemclean! - Fixes unnecessary prerendering of redirect destinations
Unnecessary files are no longer generated by static builds for redirected routes.
Requests are no longer made at build time to external redirect destination URLs, which could cause builds to fail.
Updated dependencies []:
3b8d473]:
#15888 925252e Thanks @matthewp! - Fixes a bug where dependencies imported by prerender-only server:defer islands could remain as bare imports in server output, causing module resolution failures in preview and Cloudflare Workers.
#15934 6f8f0bc Thanks @ematipico! - Updates the Astro peerDependencies#astro to be 6.0.0.
#15875 c43ef8a Thanks @matthewp! - Include workerd response details in Cloudflare prerenderer errors to make getStaticPaths() failures easier to diagnose.
Updated dependencies []:
#15815 d1872ee Thanks @matthewp! - Prebundle additional Astro runtime dependencies for Cloudflare development server, speeding up initial start time and preventing required restarts.
#15872 3b47b89 Thanks @Princesseuh! - Fixes images not working in dev mode when using the cloudflare option
Updated dependencies []:
#15711 b2bd27b Thanks @OliverSpeir! - Adds a prerenderEnvironment option to the Cloudflare adapter.
By default, Cloudflare uses its workerd runtime for prerendering static pages. Set prerenderEnvironment to 'node' to use Astro’s built-in Node.js prerender environment instead, giving prerendered pages access to the full Node.js ecosystem during both build and dev. This is useful when your prerendered pages depend on Node.js-specific APIs or NPM packages that aren’t compatible with workerd.
import cloudflare from '@astrojs/cloudflare';import { defineConfig } from 'astro/config';
export default defineConfig({ adapter: cloudflare({ prerenderEnvironment: 'node', }),});#15845 50fcc8b Thanks @aqiray! - fix: show actionable error when running astro preview without prior build
#15794 d1ac58e Thanks @OliverSpeir! - Fixes image serving in passthrough mode by using the Cloudflare ASSETS binding instead of generic fetch, which does not work in Workers for local assets
#15850 660da74 Thanks @tristanbes! - fix(cloudflare): forward configPath and other PluginConfig options to the Cloudflare Vite Plugin
Options like configPath, inspectorPort, persistState, remoteBindings, and auxiliaryWorkers were accepted by the type system but never forwarded to cfVitePlugin(), making them silently ignored.
Also fixes addWatchFile for configPath which resolved the path relative to the adapter’s node_modules directory instead of the project root.
#15843 fcd237d Thanks @Calvin-LL! - fix cloudflare image transform ignoring quality parameter
Updated dependencies []:
#15832 95e12a2 Thanks @Princesseuh! - Fixes return; syntax not working in the frontmatter correctly in certain contexts
#15803 e42b015 Thanks @merlinnot! - Fixes the Cloudflare adapter adding a SESSION KV binding even when sessions are explicitly configured to use a different driver, such as unstorage/drivers/null.
Updated dependencies []:
c2cd371]:
#14306 141c4a2 Thanks @ematipico! - Changes the API for creating a custom entrypoint, replacing the createExports() function with a direct export pattern.
If you’re using a custom entryPoint in your Cloudflare adapter config, update your existing worker file that uses createExports() to reflect the new, simplified pattern:
my-entry.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<Env> { constructor(ctx: DurableObjectState, env: Env) { super(ctx, env); }}
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<Env>, MyDurableObject: MyDurableObject, };}To create the same custom entrypoint using the updated API, export the following function instead:
my-entry.ts
import { handle } from '@astrojs/cloudflare/utils/handler';
export 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<Env>,The manifest is now created internally by the adapter.
#15435 957b9fe Thanks @rururux! - Changes the default image service from compile to cloudflare-binding. Image services options that resulted in broken images in development due to Node JS incompatiblities have now been updated to use the noop passthrough image service in dev mode. - (Cloudflare v13 and Astro6 upgrade guidance)
#15400 41eb284 Thanks @florian-lefebvre! - Removes the workerEntryPoint option, which wasn’t used anymore. Set the main field of your wrangler config instead
See how to migrate
#14306 141c4a2 Thanks @ematipico! - Development server now runs in workerd
astro dev now runs your Cloudflare application using Cloudflare’s workerd runtime instead of Node.js. This means your development environment is now a near-exact replica of your production environment—the same JavaScript engine, the same APIs, the same behavior. You’ll catch issues during development that would have only appeared in production, and features like Durable Objects, Workers Analytics Engine, and R2 bindings work exactly as they do on Cloudflare’s platform.
Previously, Astro.locals.runtime provided access to Cloudflare-specific APIs. These APIs have now moved to align with Cloudflare’s native patterns.
Update occurrences of Astro.locals.runtime:
Astro.locals.runtime.env → Import env from cloudflare:workersAstro.locals.runtime.cf → Access via Astro.request.cfAstro.locals.runtime.caches → Use the global caches objectAstro.locals.runtime (for ExecutionContext) → Use Astro.locals.cfContextHere’s an example showing how to update your code:
Before:
---const { env, cf, caches, ctx } = Astro.locals.runtime;const value = await env.MY_KV.get('key');const country = cf.country;await caches.default.put(request, response);ctx.waitUntil(promise);---
<h1>Country: {country}</h1>After:
---import { env } from 'cloudflare:workers';
const value = await env.MY_KV.get('key');const country = Astro.request.cf.country;await caches.default.put(request, response);Astro.locals.cfContext.waitUntil(promise);---
<h1>Country: {country}</h1>#15345 840fbf9 Thanks @matthewp! - Removes the cloudflareModules adapter option
The cloudflareModules option has been removed because it is no longer necessary. Cloudflare natively supports importing .sql, .wasm, and other module types.
Remove the cloudflareModules option from your Cloudflare adapter configuration if you were using it:
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare({ cloudflareModules: true })});#14445 ecb0b98 Thanks @florian-lefebvre! - Astro v6.0 upgrades to Vite v7.0 as the development server and production bundler - (v6 upgrade guidance)
#15037 8641805 Thanks @matthewp! - Updates the Wrangler entrypoint
Previously, the main field in wrangler.jsonc pointed to the built output, since Wrangler only ran in production after the build completed:
{ "main": "dist/_worker.js/index.js",}Now that Wrangler runs in both development (via workerd) and production, Astro provides a default entrypoint that works for both scenarios.
Update your wrangler.jsonc to use the new entrypoint:
{ "main": "@astrojs/cloudflare/entrypoints/server",}This single entrypoint handles both astro dev and production deployments.
#15480 e118214 Thanks @alexanderniebuhr! - Drops official support for Cloudflare Pages in favor of Cloudflare Workers
The Astro Cloudflare adapter now only supports deployment to Cloudflare Workers by default in order to comply with Cloudflare’s recommendations for new projects. If you are currently deploying to Cloudflare Pages, consider migrating to Workers by following the Cloudflare guide for an optimal experience and full feature support.
#15435 957b9fe Thanks @rururux! - Adds support for configuring the image service as an object with separate build and runtime options
It is now possible to set both a build-time and runtime service independently. Currently, 'compile' is the only available build time option. The supported runtime options are 'passthrough' (default) and 'cloudflare-binding':
import { defineConfig } from 'astro/config';import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare({ imageService: { build: 'compile', runtime: 'cloudflare-binding' }, }),});See the Cloudflare adapter imageService docs for more information about configuring your image service.
#15077 a164c77 Thanks @matthewp! - Adds support for prerendering pages using the workerd runtime.
The Cloudflare adapter now uses the new setPrerenderer() API to prerender pages via HTTP requests to a local preview server running workerd, instead of using Node.js. This ensures prerendered pages are built using the same runtime that serves them in production.
#14306 141c4a2 Thanks @ematipico! - Adds support for astro preview command
Developers can now use astro preview to test their Cloudflare Workers application locally before deploying. The preview runs using Cloudflare’s workerd runtime, giving you a staging environment that matches production exactly—including support for KV namespaces, environment variables, and other Cloudflare-specific features.
#15037 8641805 Thanks @matthewp! - The Wrangler configuration file is now optional. If you don’t have custom 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:
{ "main": "@astrojs/cloudflare/entrypoints/server", "compatibility_date": "2026-01-28", "assets": { "directory": "./dist", "binding": "ASSETS", },}You can safely delete the file. Astro will handle this configuration automatically.
You only need a wrangler config file if you’re using:
#15006 f361730 Thanks @florian-lefebvre! - Adds new session driver object shape
For greater flexibility and improved consistency with other Astro code, session drivers are now specified as an object:
import { defineConfig } from 'astro/config'import { defineConfig, sessionDrivers } from 'astro/config'
export default defineConfig({ session: { driver: 'redis', options: { url: process.env.REDIS_URL }, driver: sessionDrivers.redis({ url: process.env.REDIS_URL }), }})Specifying the session driver as a string has been deprecated, but will continue to work until this feature is removed completely in a future major version. The object shape is the current recommended and documented way to configure a session driver.
#15556 8fb329b Thanks @florian-lefebvre! - Adds support for more @cloudflare/vite-plugin options
The adapter now accepts the following options from Cloudflare’s Vite plugin:
auxiliaryWorkersconfigPathinspectorPortpersistStateremoteBindingsexperimental.headersAndRedirectsDevModeSupportFor example, you can now set inspectorPort to provide a custom port for debugging your Workers:
import { defineConfig } from 'astro/config';import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ adapter: cloudflare({ inspectorPort: 3456, }),});#15044 7cac71b Thanks @florian-lefebvre! - Removes an exposed internal API of the preview server
#15080 f67b738 Thanks @gameroman! - Updates wrangler dependency to be a peerDependency over a dependency
#15039 6cc96e7 Thanks @matthewp! - Fixes static content deployment by moving it to another folder, so Wrangler can tell the static and worker content apart
#15452 e1aa3f3 Thanks @matthewp! - Fixes server-side dependencies not being discovered ahead of time during development
Previously, imports in .astro file frontmatter were not scanned by Vite’s dependency optimizer, causing a “new dependencies optimized” message and page reload when the dependency was first encountered. Astro is now able to scan these dependencies ahead of time.
#15391 5d996cc Thanks @florian-lefebvre! - Fixes types of the handle() function exported from /handler, that could be incompatible with types generated by wrangler types
#15696 a9fd221 Thanks @Princesseuh! - Fixes duplicate logging showing up in some cases when prerendering pages
#15309 4b9c8b8 Thanks @ematipico! - Update the underneath @cloudflare/workers-types library to address a warning emitted by the package manager during the installation.
#15079 4463a55 Thanks @ascorbic! - Fixes auto-provisioning of default bindings (SESSION KV, IMAGES, and ASSETS). Default bindings are now correctly applied whether or not you have a wrangler.json file.
Previously, these bindings were only added when no wrangler config file existed. Now they are added in both cases, unless you’ve already defined them yourself.
#15694 66449c9 Thanks @matthewp! - Fixes deployment of static sites with the Cloudflare adapter
Fixes an issue with detecting and building fully static sites that caused deployment errors when using output: 'static' with the Cloudflare adapter
#15565 30cd6db Thanks @ematipico! - Fixes an issue where the use of the Code component would result in an unexpected error.
#15121 06261e0 Thanks @ematipico! - Fixes a bug where the Astro, with the Cloudflare integration, couldn’t correctly serve certain routes in the development server.
#15026 90c608c Thanks @matthewp! - Improves prebundling of internal Astro modules
#15778 4ebc1e3 Thanks @ematipico! - Fixes an issue where the computed clientAddress was incorrect in cases of a Request header with multiple values. The clientAddress is now also validated to contain only characters valid in IP addresses, rejecting injection payloads.
#15669 d5a888b Thanks @florian-lefebvre! - Removes the cssesc dependency
This CommonJS dependency could sometimes cause errors because Astro is ESM-only. It is now replaced with a built-in ESM-friendly implementation.
#15075 ee2c260 Thanks @matthewp! - Adds deprecation errors for Astro.locals.runtime properties to help migrate from Astro v5 to v6
When accessing the removed Astro.locals.runtime properties on Cloudflare, developers now receive clear error messages explaining the migration path:
Astro.locals.runtime.env → Use import { env } from "cloudflare:workers"Astro.locals.runtime.cf → Use Astro.request.cfAstro.locals.runtime.caches → Use the global caches objectAstro.locals.runtime.ctx → Use Astro.locals.cfContext#15336 9cce92e Thanks @ascorbic! - Fixes a dev server issue where framework components from linked packages would fail to load with a 504 error.
This could occur when using client:only or other client directives with components from monorepo packages (linked via file: or workspace protocol). The first request would trigger Vite’s dependency optimizer mid-request, causing concurrent client module requests to fail.
#15255 a66783a Thanks @florian-lefebvre! - Fixes a case where the types of handle() could mismatch with the ones from the user’s project. They now rely on globals, that can be obtained by running wrangler types
#15045 31074fc Thanks @ematipico! - Fixes an issue where using the Vue integration with the Cloudflare adapter resulted in some runtime errors.
#15386 a0234a3 Thanks @OliverSpeir! - Updates astro add cloudflare to use the latest valid compatibility_date in the wrangler config, if available
#15432 e2ad69e Thanks @OliverSpeir! - Removes unnecessary warning about sharp from being printed at start of dev server and build
#15588 425ea16 Thanks @rururux! - Fixes an issue where esbuild would throw a “Top-level return cannot be used inside an ECMAScript module” error during dependency scanning in certain environments.
#15450 50c9129 Thanks @florian-lefebvre! - Fixes a case where build.serverEntry would not be respected when using the new Adapter API
#15030 b5aa52b Thanks @ematipico! - Fixed an issue where the feature experimental.chromeDevtoolsWorkspace wasn’t supported by the new version of the adapter.
#15648 802426b Thanks @rururux! - Restore and fix <Code /> component functionality on Cloudflare Workers.
#15478 ee519e5 Thanks @matthewp! - Fixes fully static sites to not output server-side worker code. When all routes are prerendered, the _worker.js directory is now removed from the build output.
#15636 5ecd04c Thanks @florian-lefebvre! - Adds an error when running on Stackblitz, since workerd doesn’t support it
#15269 6f82aae Thanks @ematipico! - Fixes a regression where build.serverEntry stopped working as expected.
#15798 05771cf Thanks @rururux! - Fixes a regression where using the adapter would throw an error when using an integration that uses JSX.
#15053 674b63f Thanks @matthewp! - Excludes astro:* and virtual:astro:* from client optimizeDeps in core. Needed for prefetch users since virtual modules are now in the dependency graph.
#15495 5b99e90 Thanks @leekeh! - Refactors to use middlewareMode adapter feature (set to classic)
Updated dependencies [4ebc1e3, 4e7f3e8, a164c77, cf6ea6b, a18d727, 240c317, 745e632]:
#15778 4ebc1e3 Thanks @ematipico! - Fixes an issue where the computed clientAddress was incorrect in cases of a Request header with multiple values. The clientAddress is now also validated to contain only characters valid in IP addresses, rejecting injection payloads.
Updated dependencies [4ebc1e3, 4e7f3e8]:
745e632]:
#15696 a9fd221 Thanks @Princesseuh! - Fixes duplicate logging showing up in some cases when prerendering pages
#15694 66449c9 Thanks @matthewp! - Fixes deployment of static sites with the Cloudflare adapter
Fixes an issue with detecting and building fully static sites that caused deployment errors when using output: 'static' with the Cloudflare adapter
Updated dependencies []:
#15669 d5a888b Thanks @florian-lefebvre! - Removes the cssesc dependency
This CommonJS dependency could sometimes cause errors because Astro is ESM-only. It is now replaced with a built-in ESM-friendly implementation.
#15648 802426b Thanks @rururux! - Restore and fix <Code /> component functionality on Cloudflare Workers.
Updated dependencies []: