@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
Section titled Why Astro CloudflareCloudflare provides CDNs, web security, and other services. This adapter enhances the Astro build process to prepare your project for deployment through Cloudflare.
Installation
Section titled InstallationAstro 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.
Manual Install
Section titled Manual InstallFirst, add the @astrojs/cloudflare
adapter to your project’s dependencies using your preferred package manager.
Then, add the adapter and your desired on-demand rendering mode to your astro.config.mjs
file:
Options
Section titled OptionsimageService
Section titled imageServiceType: '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 existingnoop
service.compile
: Uses Astro’s default service (sharp), but only on pre-rendered routes at build time. During SSR for pages rendered on-demand, allastro: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’sworkerd
runtime.
platformProxy
Section titled platformProxyDetermines 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.
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
Section titled platformProxy.enabledType: { enabled?: boolean }
Default: { enabled: false }
The enabled
property allows you to enable the Cloudflare runtime in astro dev
.
platformProxy.configPath
Section titled platformProxy.configPathType: { 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
Section titled platformProxy.experimentalJsonConfigType: { experimentalJsonConfig?: boolean }
Default: { experimentalJsonConfig?: false }
The experimentalJsonConfig
property defines whether the utility reads a JSON config file (e.g. wrangler.json
).
platformProxy.persist
Section titled platformProxy.persistType: { 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.
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: "./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 (experimental). It also specifies a custom location for persisting data to the filesystem:
routes.extend
Section titled routes.extendThis 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
Section titled routes.extend.includeType: { 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
Section titled routes.extend.excludeType: { 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.
cloudflareModules
Section titled cloudflareModulesType: 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
Section titled Cloudflare runtimeThe Cloudflare runtime gives you access to environment variables and Cloudflare bindings.
The Cloudflare runtime uses bindings found in the wrangler
and .dev.vars
configuration files.
Usage
Section titled UsageFor example, if you have an environment variable configuration set up in wrangler.toml
:
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:
You can access the bindings by using Astro locals like this:
You can access the runtime from API endpoints through context.locals
:
To access the value of the MY_VARIABLE
binding add the following to your code:
See the list of all supported bindings in the Cloudflare documentation.
Typing
Section titled Typingwrangler
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.
You can type the runtime
object using Runtime
:
Cloudflare Platform
Section titled Cloudflare PlatformHeaders
Section titled HeadersYou 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.
Assets
Section titled AssetsAssets 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
Section titled RedirectsYou 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
Section titled RoutesCloudflare routing uses a _routes.json
file to determine which requests are routed to the SSR 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.
Custom _routes.json
Section titled Custom _routes.jsonCreating 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
Section titled Cloudflare Module ImportsThe cloudflare worker runtime supports imports of some non-standard module types. Most additional file types are also available in astro:
.wasm
or.wasm?module
: exports aWebAssembly.Module
that can then be instantiated.bin
: exports anArrayBuffer
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.
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
Section titled Node.js compatibilityOut 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 the import {} from 'node:*'
import syntax.
You’ll also need to modify the vite
configuration in your astro config to allow for the node:*
import syntax:
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.
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.
Preview with Wrangler
Section titled Preview with WranglerTo use wrangler
to run your application locally, update the preview script:
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
Section titled Meaningful error messagesCurrently, 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
.