@astrojs/ cloudflare

This adapter allows Astro to deploy your hybrid or server rendered site to Cloudflare.

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 Pages deployment guide.

Why Astro Cloudflare

Cloudflare provides CDNs, web security, and other services. This adapter enhances the Astro build process to prepare your 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

mode

Type: 'advanced' | 'directory'
Default: 'advanced'

This configuration option defines how your Astro project is deployed to Cloudflare Pages.

advanced mode picks up the _worker.js file in the dist folder
directory mode picks up the files in the functions folder, by default only one [[path]].js file is generated

Switching to directory mode allows you to add additional files manually such as Cloudflare Pages Plugins, Cloudflare Pages Middleware or custom functions using Cloudflare Pages Functions Routing.

export default defineConfig({
  adapter: cloudflare({ mode: 'directory' }),
});

To compile a separate bundle for each page, set the functionPerRoute option in your Cloudflare adapter config. This option requires some manual maintenance of the functions folder. Files emitted by Astro will overwrite existing files with identical names in the functions folder, so you must choose unique file names for each file you manually add. Additionally, the adapter will never empty the functions folder of outdated files, so you must clean up the folder manually when you remove pages.

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

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    functionPerRoute: true
  })
})

This adapter doesn’t support the edgeMiddleware option.

routes.strategy

Type: 'auto' | 'include' | 'exclude'
Default: 'auto'

Determines how routes.json will be generated if no custom _routes.json is provided.

There are three options available:

"auto" (default): Will automatically select the strategy that generates the fewest entries. This should almost always be sufficient, so choose this option unless you have a specific reason not to.
include: Pages and endpoints that are not pre-rendered are listed as include entries, telling Cloudflare to invoke these routes as functions. exclude entries are only used to resolve conflicts. Usually the best strategy when your website has mostly static pages and only a few dynamic pages or endpoints.

Example: For src/pages/index.astro (static), src/pages/company.astro (static), src/pages/users/faq.astro (static) and /src/pages/users/[id].astro (SSR) this will produce the following _routes.json:
dist/_routes.json
```
{
  "version": 1,
  "include": [
    "/_image", // Astro's image endpoint
    "/users/*" // Dynamic route
  ],
  "exclude": [
    // Static routes that needs to be exempted from the dynamic wildcard route above
    "/users/faq/",
    "/users/faq/index.html"
  ]
}
```
exclude: Pre-rendered pages are listed as exclude entries (telling Cloudflare to handle these routes as static assets). Usually the best strategy when your website has mostly dynamic pages or endpoints and only a few static pages.

Example: For the same pages as in the previous example this will produce the following _routes.json:
dist/_routes.json
```
{
  "version": 1,
  "include": [
    "/*" // Handle everything as function except the routes below
  ],
  "exclude": [
    // All static assets
    "/",
    "/company/",
    "/index.html",
    "/users/faq/",
    "/favicon.png",
    "/company/index.html",
    "/users/faq/index.html"
  ]
}
```

routes.include

Type: string[]
Default: []

If you want to use the automatic _routes.json generation, but want to include additional routes (e.g. when having custom functions in the functions folder), you can use the routes.include option to add additional routes to the include array.

routes.exclude

Type: string[]
Default: []

If you want to use the automatic _routes.json generation, but want to exclude additional routes, you can use the routes.exclude option to add additional routes to the exclude array.

The following example automatically generates _routes.json while including and excluding additional routes. Note that that is only necessary if you have custom functions in the functions folder that are not handled by Astro.

export default defineConfig({
  adapter: cloudflare({
    mode: 'directory',
    routes: {
      strategy: 'include',
      include: ['/users/*'], // handled by custom function: functions/users/[id].js
      exclude: ['/users/faq'], // handled by static page: pages/users/faq.astro
    },
  }),
});

imageService

Type: 'passthrough' | 'cloudflare' | 'compile'
Default: 'passthrough'

Determines which image service is used by the adapter. The adapter will default to passthrough 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.

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

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

`wasmModuleImports`

Type: true | false
Default: false

Whether or not to import .wasm files directly as ES modules using the .wasm?module import syntax.

Add wasmModuleImports: true to astro.config.mjs to enable this functionality in both the Cloudflare build and the Astro dev server. Read more about using Wasm modules.

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

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

runtime

Type:

{ mode: 'off' }
| { mode: 'local'; type: 'pages'; persistTo?: string; bindings?: Record<string, CF_BINDING> }
| { mode: 'local'; type: 'workers'; persistTo?: string; };

(CF_BINDING type reference)
Default: { mode: 'off', persistTo: '' }

Determines whether and how the Cloudflare Runtime is added to astro dev. Read more about the Cloudflare Runtime.

The type property defines where your Astro project is deployed to:

pages: Deployed to Cloudflare Pages
workers: Deployed to Cloudflare Workers

The mode property defines what you want the runtime to support in astro dev:

off: no access to the runtime using astro dev. You can choose Preview with Wrangler when you need access to the runtime, to simulate the production environment locally.
local: uses a local runtime powered by miniflare and workerd, which supports Cloudflare’s Bindings. Only if you want to use unsupported features, such as eval, bindings with no local support choose Preview with Wrangler

In mode: local, you have access to the persistTo property which defines where the local bindings state is saved. This avoids fresh bindings on every restart of the dev server. This value is a directory relative to your astro dev execution path. By default it is set to .wrangler/state/v3 to allow usage of wrangler cli commands (e.g. for migrations). Add this path to your .gitignore.

Cloudflare runtime

The Cloudflare runtime gives you access to environment variables and Cloudflare bindings. You can find more information in Cloudflare’s Workers and Pages docs. Depending on your deployment type (pages or workers), you need to configure the bindings differently.

Currently supported bindings:

Config

Cloudflare Pages

Cloudflare Pages does not support a configuration file.

To deploy your pages project to production, you need to configure the bindings using Cloudflare’s Dashboard. To be able to access bindings locally, you need to configure them using the adpater’s runtime option.

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    runtime: {
      mode: 'local',
      type: 'pages',
      bindings: {
        // example of a var binding (environment variable)
        "URL": {
          type: "var",
          value: "https://example.com",
        },
        // example of a KV binding
        "KV": {
          type: "kv",
        },
        // example of a D1 binding
        "D1": {
          type: "d1",
        },
        // example of a R2 binding
        "R2": {
          type: "r2",
        },
        // example of a Durable Object binding
        "DO": {
          type: "durable-object",
          className: "DO",
        },
      },
    },
  }),
});

If you also need to define secrets in addition to enviroment variables, you need to add a .dev.vars file to the root of the Astro project:

DB_PASSWORD=myPassword

If you want to use wrangler for cli commands, e.g. D1 migrations, you also need to add a wrangler.toml to the root of the Astro project with the correct content. Consult Cloudflare’s documentation for further details.

name = "example"
compatibility_date = "2023-06-14"

# example for D1 Binding
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

Cloudflare Workers

To deploy your workers project to production, you need to configure the bindings using a wrangler.toml config file in the root directory of your Astro project. To be able to access bindings locally, the @astrojs/cloudflare adapter will also read the wrangler.toml file.

name = "example"

# example of a KV Binding
kv_namespaces = [
    { binding = "KV", id = "KV", preview_id = "KV" },
]

# example of a var binding (environment variables)
[vars]
URL = "example.com"

# example of a D1 Binding
[[d1_databases]]
binding = "D1"
database_name = "D1"
database_id = "D1"
preview_database_id = "D1"

# example of a R2 Binding
[[r2_buckets]]
binding = 'R2'
bucket_name = 'R2'

# example of a Durable Object Binding
[[durable_objects.bindings]]
name = "DO"
class_name = "DO"

If you also need to define secrets in addition to environment variables, you need to add a .dev.vars file to the root of the Astro project:

DB_PASSWORD=myPassword

Usage

You can access the runtime from Astro components through Astro.locals inside any .astro file.

---
const runtime = Astro.locals.runtime;
---

<pre>{JSON.stringify(runtime.env)}</pre>

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');
}

Typing

If you have configured mode: advanced, you can type the runtime object using AdvancedRuntime:

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

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

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

If you have configured mode: directory, you can type the runtime object using DirectoryRuntime:

/// <reference types="astro/client" />

type KVNamespace = import('@cloudflare/workers-types/experimental').KVNamespace;
type ENV = {
  SERVER_URL: string;
  KV_BINDING: KVNamespace;
};

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

declare namespace App {
  interface Locals extends Runtime {
    user: {
      name: string;
      surname: string;
    };
  }
}

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.

Redirects

You can declare custom redirects using Cloudflare Pages. This allows you to redirect requests to a different URL. You can add a _redirects file in your Astro project’s public/ folder. This file will be copied to your build output directory.

Routes

You can define which routes are invoking functions and which are static assets, using Cloudflare routing via a _routes.json file. This file is automatically generated by Astro.

Custom `_routes.json`

By default, @astrojs/cloudflare will generate a _routes.json file with include and exclude rules based on your applications’s dynamic and static routes. This will enable Cloudflare to serve files and process static redirects without a function invocation. Creating a custom _routes.json will override this automatic optimization. See Cloudflare’s documentation on creating a custom routes.json for more details.

Use Wasm modules

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

import mod from '../util/add.wasm?module';

// instantiate ahead of time to share module
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.

Node.js compatibility

Astro’s Cloudflare adapter allows you to use any Node.js runtime API supported by Cloudflare:

assert
AsyncLocalStorage
Buffer
Crypto
Diagnostics Channel
EventEmitter
path
process
Streams
StringDecoder
util

To use these APIs, your page or endpoint must be server-side rendered (not pre-rendered) and must use the the import {} from 'node:*' import syntax.

export const prerender = false;
import { Buffer } from 'node:buffer';

Additionally, you’ll need to enable the Compatibility Flag in Cloudflare. The configuration for this flag may vary based on where you deploy your Astro site. For detailed guidance, please refer to the Cloudflare documentation on enabling Node.js compatibility.

Cloudflare module support

All Cloudflare namespaced packages (e.g. cloudflare:sockets) are allowlisted for use. Note that the package cloudflare:sockets does not work locally without using Wrangler dev mode.

Preview with Wrangler

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

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

wrangler gives you access to Cloudflare bindings, environment variables, and the cf object. Getting hot reloading or 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,
    },
  },
});