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

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.

1. Install Wrangler CLI.

   Terminal window

   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
   • pnpm
   • Yarn
   Terminal window

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

   • Static
   • On demand
   wrangler.jsonc

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

4. Preview your project locally with Wrangler.

   Terminal window

   npx astro build && npx wrangler dev

5. Deploy using npx wrangler deploy.

   Terminal window

   npx astro build && npx wrangler deploy

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

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.

1. Install Wrangler CLI.

   • npm
   • pnpm
   • Yarn
   Terminal window

   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
   • pnpm
   • Yarn
   Terminal window

   npx 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:

   • Static
   • On demand
   wrangler.jsonc

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

   Read more about on-demand rendering in Astro.

4. Preview your project locally with Wrangler.

   • npm
   • pnpm
   • Yarn
   Terminal window

   npx astro build && wrangler pages dev ./dist

5. Deploy using npx wrangler deploy.

   • npm
   • pnpm
   • Yarn
   Terminal window

   npx astro build && wrangler pages deploy ./dist

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

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.

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.

More Deployment Guides