Deploy your Astro Site to Cloudflare

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:

• How to deploy to Cloudflare Workers
• How to deploy to Cloudflare Pages

Заметка

Cloudflare recommends using Cloudflare Workers for new projects. For existing Pages projects, refer to Cloudflare’s migration guide and compatibility matrix.

Read more about using the Cloudflare runtime in your Astro project.

Prerequisites

To get started, you will need:

• A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process.

Cloudflare Workers

How to deploy with Wrangler

1. Install Wrangler CLI.

   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.

   npm

   npx astro add cloudflare

   pnpm

   pnpm astro add cloudflare

   Yarn

   yarn astro add cloudflare

   Read more about on-demand rendering in Astro.

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.

   Статический

   wrangler.jsonc

   {
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "assets": {
       "directory": "./dist",
     }
   }

   По запросу

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

4. Preview your project locally with Wrangler.

   npx astro build && npx wrangler dev

5. Deploy using npx wrangler deploy.

   npx astro build && npx wrangler deploy

After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.

Read more about using Cloudflare runtime APIs such as bindings.

How to deploy with CI/CD

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:

1. Follow Steps 1-3 from the Wrangler section above.

2. Log in to the Cloudflare dashboard and navigate to Workers & Pages. Select Create.

3. Under Import a repository, select a Git account and then the repository containing your Astro project.

4. Configure your project with:

   • Build command: npx astro build
   • Deploy command: npx wrangler deploy

5. Click Save and Deploy. You can now preview your Worker at its provided workers.dev subdomain.

Cloudflare Pages

How to deploy with Wrangler

1. Install Wrangler CLI.

   npm

   npm install wrangler@latest --save-dev

   pnpm

   pnpm add wrangler@latest --save-dev

   Yarn

   yarn add wrangler@latest --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.

   npm

   npx astro add cloudflare

   pnpm

   pnpm astro add cloudflare

   Yarn

   yarn astro add cloudflare

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:

   Статический

   wrangler.jsonc

   {
     "name": "my-astro-app",
     "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
     "pages_build_output_dir": "./dist"
   }

   По запросу

   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"
   }

   Read more about on-demand rendering in Astro.

4. Preview your project locally with Wrangler.

   npm

   npx astro build && wrangler pages dev ./dist

   pnpm

   pnpm astro build && wrangler pages dev ./dist

   Yarn

   yarn astro build && wrangler pages dev ./dist

5. Deploy using npx wrangler deploy.

   npm

   npx astro build && wrangler pages deploy ./dist

   pnpm

   pnpm astro build && wrangler pages deploy ./dist

   Yarn

   yarn astro build && wrangler pages deploy ./dist

After your assets are uploaded, Wrangler will give you a preview URL to inspect your site.

How to deploy a site with CI/CD

1. Push your code to your git repository (e.g. GitHub, GitLab).

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

3. Configure your project with:

   • Framework preset: Astro
   • Build command: npm run build
   • Build output directory: dist

4. Click the Save and Deploy button.

Troubleshooting

404 behavior

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.

wrangler.jsonc

{
  "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

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.

Node.js runtime APIs

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.

Дополнительные руководства по развёртыванию

• 

  AWS

• 

  AWS via Flightcontrol

• 

  AWS via SST

• 

  Azion

• 

  Buddy

• 

  Cleavr

• 

  Clever Cloud

• 

  Cloudflare

• 

  CloudRay

• 

  Deno Deploy

• 

  DeployHQ

• 

  EdgeOne Pages

• 

  Firebase

• 

  Fleek

• 

  Fly.io

• 

  GitHub Pages

• 

  GitLab Pages

• 

  Google Cloud

• 

  Heroku

• 

  Juno

• 

  Kinsta

• 

  Microsoft Azure

• 

  Netlify

• 

  Railway

• 

  Render

• 

  Seenode

• 

  Stormkit

• 

  Surge

• 

  Vercel

• 

  Zeabur

• 

  Zephyr Cloud

• 

  Zerops