src/content/docs/en/guides/deploy/cloudflare.mdx
import ReadMore from '/components/ReadMore.astro';
import { Steps } from '@astrojs/starlight/components';
import StaticSsrTabs from '/components/tabs/StaticSsrTabs.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as on-demand rendered sites, to both Cloudflare Workers and Cloudflare Pages.
This guide includes:
:::note
Cloudflare recommends using Cloudflare Workers for new projects. For existing Pages projects, refer to Cloudflare's migration guide and compatibility matrix.
:::
<ReadMore>Read more about using the Cloudflare runtime in your Astro project.</ReadMore>
To get started, you will need:
```bash
npm install wrangler@latest --save-dev
```
2. If your site uses on-demand rendering, install the @astrojs/cloudflare adapter.
This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step.
<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro add cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro add cloudflare
```
</Fragment>
</PackageManagerTabs>
<ReadMore>Read more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/).</ReadMore>
3. Create a Wrangler configuration file.
Running `astro add cloudflare` will create this for you; if you are not using the adapter, you'll need to create it yourself.
<StaticSsrTabs>
<Fragment slot="static">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"assets": {
"directory": "./dist",
}
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc title="wrangler.jsonc"
{
"main": "dist/_worker.js/index.js",
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": "./dist"
},
"observability": {
"enabled": true
}
}
```
</Fragment>
</StaticSsrTabs>
4. Preview your project locally with Wrangler.
```bash
npx astro build && npx wrangler dev
```
5. Deploy using npx wrangler deploy.
```bash
npx astro build && npx wrangler deploy
```
After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.
<ReadMore>Read more about using Cloudflare runtime APIs such as bindings.</ReadMore>
You can also use a CI/CD system such as Workers Builds (BETA) to automatically build and deploy your site on push.
If you're using Workers Builds:
<Steps> 1. Follow Steps 1-3 from the Wrangler section above.Log in to the Cloudflare dashboard and navigate to Workers & Pages. Select Create.
Under Import a repository, select a Git account and then the repository containing your Astro project.
Configure your project with:
npx astro buildnpx wrangler deployClick Save and Deploy. You can now preview your Worker at its provided workers.dev subdomain.
<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add wrangler@latest --dev
```
</Fragment>
</PackageManagerTabs>
2. If your site uses on-demand rendering, install the @astrojs/cloudflare adapter.
This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step.
<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro add cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro add cloudflare
```
</Fragment>
</PackageManagerTabs>
3. Create a Wrangler configuration file.
Because Cloudflare recommends new projects use Workers instead of Pages, the `astro add cloudflare` command creates a `wrangler.jsonc` and `public/.assetsignore` file, which are specific to Workers projects. You will need to delete the `public/.assetsignore` file and change your `wrangler.jsonc` file. If you are not using the adapter you'll need to create it yourself.
Ensure your `wrangler.jsonc` file is structured like this:
<StaticSsrTabs>
<Fragment slot="static">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"pages_build_output_dir": "./dist"
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"compatibility_flags": [
"nodejs_compat",
"disable_nodejs_process_v2"
],
"pages_build_output_dir": "./dist"
}
```
</Fragment>
</StaticSsrTabs>
<ReadMore>Read more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/).</ReadMore>
3. Preview your project locally with Wrangler.
<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages dev ./dist
```
</Fragment>
</PackageManagerTabs>
4. Deploy using npx wrangler deploy.
<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages deploy ./dist
```
</Fragment>
</PackageManagerTabs>
After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.
Log in to the Cloudflare dashboard and navigate to Compute (Workers) > Workers & Pages. Select Create and then select the Pages tab. Connect your git repository.
Configure your project with:
Astronpm run builddistClick the Save and Deploy button.
</Steps>For Workers projects, you will need to set not_found_handling if you want to serve a custom 404 page. You can read more about this in the Routing behavior section of Cloudflare's documentation.
{
"assets": {
"directory": "./dist",
"not_found_handling": "404-page"
}
}
For Pages projects, if you include a custom 404 page, it will be served by default. Otherwise, Pages will default to Cloudflare's single-page application rendering behavior and redirect to the home page instead of showing a 404 page.
Client-side hydration may fail as a result of Cloudflare's Auto Minify setting. If you see Hydration completed but contains mismatches in the console, make sure to disable Auto Minify under Cloudflare settings.
If you are building a project that is using on-demand rendering with the Cloudflare adapter and the server fails to build with an error message such as [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.:
This means that a package or import you are using in the server-side environment is not compatible with the Cloudflare runtime APIs.
If you are directly importing a Node.js runtime API, please refer to the Astro documentation on Cloudflare's Node.js compatibility for further steps on how to resolve this.
If you are importing a package that imports a Node.js runtime API, check with the author of the package to see if they support the node:* import syntax. If they do not, you may need to find an alternative package.