@astrojs/ cloudflare

This adapter allows Astro to deploy your on-demand rendered routes to Cloudflare.

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

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

Why Astro Cloudflare

Cloudflare’s Developer Platform 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 instead.

Add the Cloudflare adapter to enable SSR 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.

npx astro add cloudflare

pnpm astro add cloudflare

yarn astro add cloudflare

Manual Install

First, add the @astrojs/cloudflare adapter to your project’s dependencies using your preferred package manager.

npm install @astrojs/cloudflare

pnpm add @astrojs/cloudflare

yarn add @astrojs/cloudflare

Then, add the adapter and your desired on-demand rendering mode to your astro.config.mjs file:

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

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

Options

imageService

Type: 'passthrough' | 'cloudflare' | '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 service.
passthrough: Uses the existing noop service.
compile: Uses Astro’s default service (sharp), but only on pre-rendered routes at build time. During SSR for pages rendered on-demand, all astro:assets features are disabled.
custom: Always uses the image service configured in Image Options. This option will not check to see whether the configured image service works in Cloudflare’s workerd runtime.

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

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

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.

platformProxy.enabled

Type: { enabled?: boolean }
Default: { enabled: false }

The enabled property allows you to enable the Cloudflare runtime in astro dev.

platformProxy.configPath

Type: { configPath?: string }
Default: { configPath: 'wrangler.toml' }

The configPath allows you to define your Wrangler configuration file, relative to the root of your Astro project.

platformProxy.experimentalJsonConfig

Type: { experimentalJsonConfig?: boolean }
Default: { experimentalJsonConfig?: false }

The experimentalJsonConfig property defines whether the utility reads a JSON config file (e.g. wrangler.json).

platformProxy.persist

Type: { persist?: boolean | { path: string } }
Default: { persist: true }

The persist property defines if and where the bindings data is persistent. true defaults to the same location used by Wrangler so data can be shared between the two. If false, no data is persisted to or read from the filesystem.

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 (experimental). It also specifies a custom location for persisting data to the filesystem:

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

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

routes.extend

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

Configure 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

Configure 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 SSR 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 SSR function.

export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // Route a prerended page to the SSR function for on-demand rendering
        exclude: [{ pattern: '/pagefind/*' }], // Use Starlight's pagefind search, which is generated statically at build time
      }
    },
  }),
});

`cloudflareModules`

Type: true | false
Default: true

Enables imports of .wasm, .bin, and .txt modules.

This functionality is enabled by default. If you’d like to disable it, set cloudflareModules: false.

Cloudflare runtime

Usage

The Cloudflare runtime gives you access to environment variables and bindings to Cloudflare resources. The Cloudflare runtime uses bindings found in the wrangler.toml/wrangler.json configuration file.

You can access the bindings from Astro.locals.runtime:

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

You can access the runtime from API endpoints through context.locals:

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

  return new Response('Some body');
}

See the list of all 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 in wrangler.json as follows:

{
  "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 rather than in your Wrangler config file.

npx wrangler secret put <KEY>

To set secrets for local development, you also need to add a .dev.vars file to the root of the Astro project:

DB_PASSWORD=myPassword

You can then access environment variables, including secrets, from the env object available from Astro.locals.runtime:

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

Cloudflare environment variables and secrets are compatible with the astro:env API.

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 for more information.

Every time you change your configuration files (e.g. wrangler.toml, .dev.vars) you need to run wrangler types.

You can create a pnpm script to run wrangler types automatically before other commands.

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

You can type the runtime object using Runtime:

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

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

Cloudflare Platform

Headers

You can attach custom 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.

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

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 SSR. Read more about static asset routing with Cloudflare Workers.

Unlike Cloudflare Pages, with Workers, you do not need a _routes.json file.

Routing on Cloudflare Pages

For Cloudflare Pages, routing 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 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 for more details.

Cloudflare Module Imports

The Cloudflare workerd runtime supports imports of some non-standard module types. Most additional file types are also available in Astro:

.wasm or .wasm?module: exports a WebAssembly.Module that can then be instantiated
.bin: exports an ArrayBuffer of the raw binary contents of the file
.txt: Exports a string of the file contents

All module types export a single default value. Modules can be imported both from server-side rendered pages, or from prerendered pages for static site generation.

The following is an example of importing a Wasm module that then responds to requests by adding the request’s number parameters together.

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

// Instantiate first in order to use it
const addModule: any = new WebAssembly.Instance(mod);

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

While this example is trivial, Wasm can be used to accelerate computationally intensive operations which do not involve significant I/O such as embedding an image processing library, or embedding a small pre-indexed database for search over a read-only dataset.

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.

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.

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:

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

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

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.

Preview with Wrangler

To use wrangler to run your application locally, update the preview script.

For Workers:

"preview": "wrangler dev ./dist"

For Pages:

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

Developing with wrangler gives you access to Cloudflare bindings, environment variables, and the cf object. Getting hot reloading of the Astro dev server to work with Wrangler might require custom setup. See community examples.

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, you can add vite.build.minify = false setting to your astro.config.mjs.

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