InstallSection titled Install
Add the Cloudflare adapter to enable SSR in your Astro project with the following
astro add command. This will install the adapter and make the appropriate changes to your
astro.config.mjs file in one step.
If you prefer to install the adapter manually instead, complete the following two steps:
- Add the Cloudflare adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal:
- Add the following to your
OptionsSection titled Options
mode: "advanced" | "directory"
Cloudflare Pages has 2 different modes for deploying functions,
advanced mode which picks up the
dist, or a directory mode where pages will compile the worker out of a functions folder in the project root.
For most projects the adapter default of
advanced will be sufficient; the
dist folder will contain your compiled project. Switching to directory mode allows you to use pages plugins such as Sentry or write custom code to enable logging.
In directory mode the adapter will compile the client side part of your app the same way, but moves the worker script into a
functions folder in the project root. The adapter will only ever place a
[[path]].js in that folder, allowing you to add additional plugins and pages middleware which can be checked into version control. Cloudflare documentation contains more information about writing custom functions.
Enabling PreviewSection titled Enabling Preview
In order for preview to work you must install
It’s then possible to update the preview script in your
"preview": "wrangler pages dev ./dist". This will allow you to run your entire application locally with Wrangler, which supports secrets, environment variables, KV namespaces, Durable Objects and all other supported Cloudflare bindings.
Access to the Cloudflare runtimeSection titled Access to the Cloudflare runtime
You can access all the Cloudflare bindings and environment variables from Astro components and API routes through the adapter API.
Depending on your adapter mode (advanced = worker, directory = pages), the runtime object will look a little different due to differences in the Cloudflare API.
Environment VariablesSection titled Environment Variables
See Cloudflare’s documentation for working with environment variables.
Headers, Redirects and function invocation routesSection titled Headers, Redirects and function invocation routes
Cloudflare has support for adding custom headers, configuring static redirects and defining which routes should invoke functions. Cloudflare looks for
_routes.json files in your build output directory to configure these features. This means they should be placed in your Astro project’s
Custom Section titled Custom _routes.json
@astrojs/cloudflare will generate a
_routes.json file that lists all files from your
dist/ folder and redirects from the
_redirects file in the
exclude array. 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 and, if not configured manually, cause function invocations that will count against the request limits of your Cloudflare plan.
TroubleshootingSection titled Troubleshooting
For help, check out the
#support channel on Discord. Our friendly Support Squad members are here to help!
You can also check our Astro Integration Documentation for more on integrations.
Meaningful error messagesSection titled 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
ContributingSection titled Contributing
This package is maintained by Astro’s Core team. You’re welcome to submit an issue or PR!