Astro - Cloudflare

This adapter allows Astro to deploy your on-demand rendered routes and features to Cloudflare, including server islands, actions, and sessions.

On this page

Introduction

If you’re using Astro as a static site builder, you don’t need an adapter.

Learn how to deploy your Astro site in Cloudflare deployment guide.

Getting started

Run the create astro command:

Terminal window
bun create astro@latest -- --ref next
Terminal window
bun install

Add the Cloudflare adapter to enable server-rendering in your Astro project with the astro add command. This will install @astrojs/cloudflare and make the appropriate changes to your astro.config.mjs file in one step.

Terminal window
bun astro add cloudflare

Now, you can enable on-demand rendering per page, or set your build output configuration to output: 'server' to server-render all your pages by default.

workerd

astro dev and astro preview 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.

astro dev can run your entire application using workerd, Cloudflare’s open-source JavaScript runtime. This is the same runtime that powers Cloudflare Workers in production — not a simulation or polyfill.

You can now develop directly against real platform APIs, catching issues during development rather than after deployment.

When you run astro dev with Cloudflare support, you now have access to:

  • Durable Objects – Test stateful serverless objects locally
  • KV Namespaces – Develop against real key-value storage
  • R2 Storage – Work with object storage in dev
  • Workers Analytics Engine – Test analytics collection
  • Environment variables & secrets – Full config support
  • Hot Module Replacement (HMR) – Real-time updates while running inside workerd

Access your Cloudflare bindings directly using the cloudflare:workers module:

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


// Access KV storage directly - works in both dev and production
const kv = env.MY_KV_NAMESPACE;
await kv.put("visits", "1");
const visits = await kv.get("visits");
---
<p>Visits: {visits}</p>

The Cloudflare adapter has also been significantly enhanced alongside the new dev server:

  • astro preview now works with Cloudflare, letting you test your built application locally before deploying
  • Integration API updates for custom entrypoints and dev server configuration
  • Improved error messages when your code differs from production behavior

Currently, prerendered (static) builds do not run through workerd, but they will before v6 is released.

Astro 6 requires @astrojs/cloudflare v13 or later.

Pending

jjj