Skip to content

Deploy your Astro Site to Cloudflare Pages

You can deploy your Astro project on Cloudflare Pages, a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites.

This guide includes:

Prerequisites

Section titled 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.
  • Your app code pushed to a GitHub or a GitLab repository.

How to deploy a site with Git

Section titled How to deploy a site with Git

  1. Set up a new project on Cloudflare Pages.

  2. Push your code to your git repository (GitHub, GitLab).

  3. Log in to the Cloudflare dashboard and select your account in Account Home > Workers & Pages > Overview.

  4. Select Create application, then the Pages tab and then select the Connect to Git option.

  5. Select the git project you want to deploy and click Begin setup

  6. Use the following build settings:

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

  7. Click the Save and Deploy button.

How to deploy a site using Wrangler

Section titled How to deploy a site using Wrangler

  1. Install Wrangler CLI.

  2. Authenticate Wrangler with your Cloudflare account using wrangler login.

  3. Run your build command.

  4. Deploy using npx wrangler pages deploy dist.

Terminal window
# Install Wrangler CLI
npm install -g wrangler
# Login to Cloudflare account from CLI
wrangler login
# Run your build command
npm run build
# Create new deployment
npx wrangler pages deploy dist

After your assets are uploaded, Wrangler will give you a preview URL to inspect your site. When you log into the Cloudflare Pages dashboard, you will see your new project.

Enabling Preview locally with Wrangler

Section titled Enabling Preview locally with Wrangler

For the preview to work, you must install wrangler

Terminal window
pnpm add wrangler --save-dev

It’s then possible to update the preview script to run wrangler instead of Astro’s built-in preview command:

package.json
"preview": "wrangler pages dev ./dist"

How to deploy an SSR site

Section titled How to deploy an SSR site

You can build an Astro SSR site for deployment to Cloudflare Pages using the @astrojs/cloudflare adapter.

Follow the steps below to set up the adapter. You can then deploy using either of the approaches documented above.

Quick install

Section titled Quick 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.

Terminal window
npx astro add cloudflare

Manual install

Section titled Manual install

If you prefer to install the adapter manually instead, complete the following two steps:

  1. Add the @astrojs/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:

    Terminal window
    npm install @astrojs/cloudflare

  2. Add the following to your astro.config.mjs file:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';
    

    export default defineConfig({
      output: 'server',
      adapter: cloudflare()
    });
Read more about SSR in Astro.

Troubleshooting

Section titled Troubleshooting

Client-side hydration

Section titled 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

Section titled Node.js runtime APIs

If you are building a project that is using on-demand rendering with the Cloudflare SSR 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