Skip to content

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 Cloudflare Workers.

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

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.

Cloudflare Workers

Section titled “Cloudflare Workers”

How to deploy with cf

Section titled “How to deploy with cf”

  1. Install Cloudflare CLI.

    Terminal window
    npm install cf@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.

    Terminal window
    npx astro add cloudflare
    Read more about on-demand rendering in Astro.

  3. Create a Cloudflare 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.

    cloudflare.config.ts
    import { defineConfig } from 'cf/config';
    

    export default defineConfig({
      worker: {
        name: 'my-astro-app',
        compatibilityDate: 'YYYY-MM-DD', // Update to the day you deploy
      },
    });

  4. Preview your project locally with cf.

    Terminal window
    npx cf dev

  5. Deploy using npx cf deploy.

    Terminal window
    npx cf deploy

After your assets are uploaded, cf 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

Section titled “How to deploy with CI/CD”

You can also use a CI/CD system such as Workers Builds to automatically build and deploy your site on push.

If you’re using Workers Builds:

  1. Follow Steps 1-3 from the Cloudflare CLI section above.

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

  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 cf build
    • Deploy command: npx cf deploy --prebuilt

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

Troubleshooting

Section titled “Troubleshooting”

404 behavior

Section titled “404 behavior”

For Workers projects, you will need to set notFoundHandling if you want to serve a custom 404 page. You can read more about this in the Routing behavior section of Cloudflare’s documentation.

cloudflare.config.ts
import { defineConfig } from 'cf/config';


export default defineConfig({
  worker: {
    name: 'my-astro-app',
    assets: {
      notFoundHandling: '404-page',
    },
  },
});

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.

More Deployment Guides

Contribute Community Sponsor