From 7046fb980c4f1c45c240daca681786e86e6c8825 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Sat, 14 Mar 2026 20:11:46 +0100 Subject: [PATCH 1/6] remove CF Pages workaround --- .../guides/integrations-guide/cloudflare.mdx | 39 ------------------- 1 file changed, 39 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 22da4fc8c2bb9..499f75ab91f86 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -428,43 +428,6 @@ export default defineConfig({ }); ``` -## Using with Cloudflare Pages - -The Cloudflare adapter deploys to Cloudflare Workers by default. To deploy to Cloudflare Pages instead, additional manual configuration is required. - -:::caution -Cloudflare recommends using Workers for new projects. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for more information if you have an existing project using Pages. -::: - - -1. Configure your build output directories in `astro.config.mjs`: - - ```js title="astro.config.mjs" ins={6-9} - import { defineConfig } from 'astro/config'; - import cloudflare from '@astrojs/cloudflare'; - - export default defineConfig({ - adapter: cloudflare(), - build: { - client: './', - server: './_worker.js', - }, - }); - ``` - -2. Create a `_routes.json` file in your `public/` folder to route requests to your Worker: - - ```jsonc title="public/_routes.json" - { - "version": 1, - "include": ["/*"], // Alternatively, specify specific routes - "exclude": ["/static/*"] // Exclude static assets if needed - } - ``` - - See the [Cloudflare documentation on routing with Pages](https://developers.cloudflare.com/pages/functions/routing/#create-a-_routesjson-file) for more details. - - ## Upgrading to v13 and Astro 6 Astro 6 brings significant improvements to the Cloudflare development experience and requires `@astrojs/cloudflare` v13 or later. Now, `astro dev` uses Cloudflare's Vite plugin and `workerd` runtime to closely mirror production behavior. @@ -683,8 +646,6 @@ The Astro Cloudflare adapter now only supports deploying to Cloudflare Workers b See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for detailed migration instructions. -If you need to continue using Cloudflare Pages, see [Using with Cloudflare Pages](#using-with-cloudflare-pages) for the required manual configuration. - ### Changed: `imageService` default The default value of `imageService` has changed from `'compile'` to `'cloudflare-binding'` for an improved experience when working with images. From edb8a3073a843849607bcecbeb1b9993db51ceb2 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Tue, 17 Mar 2026 20:22:05 +0100 Subject: [PATCH 2/6] apply suggestion Co-authored-by: Armand Philippot <59021693+ArmandPhilippot@users.noreply.github.com> --- src/content/docs/en/guides/integrations-guide/cloudflare.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 499f75ab91f86..592fdabe4400c 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -640,9 +640,9 @@ export default defineConfig({ Use `astro preview` to test your Cloudflare Workers application locally before deploying. The preview runs using Cloudflare's `workerd` runtime, closely mirroring production behavior. Run `astro build` followed by `astro preview` to start the preview server. -### Deprecated: Cloudflare Pages support +### Removed: Cloudflare Pages support -The Astro Cloudflare adapter now only supports deploying to Cloudflare Workers by default. If you are currently deploying to Cloudflare Pages, consider migrating to Workers for the best experience and feature support. +The Astro Cloudflare adapter no longer supports deployment on Cloudflare Pages. For the best experience and feature support, you should migrate to Cloudflare Workers. See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for detailed migration instructions. From 9bf17838dbe026248ead8884d27f8c23f24df171 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Tue, 17 Mar 2026 21:20:59 +0100 Subject: [PATCH 3/6] update deploy guide --- .../docs/en/guides/deploy/cloudflare.mdx | 145 +----------------- 1 file changed, 2 insertions(+), 143 deletions(-) diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index 5c5d28f19471e..20da431e60d33 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -13,12 +13,11 @@ 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](https://developers.cloudflare.com/workers/static-assets/) and [Cloudflare Pages](https://pages.cloudflare.com/). +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](https://developers.cloudflare.com/workers/static-assets/). This guide includes: - [How to deploy to Cloudflare Workers](#cloudflare-workers) -- [How to deploy to Cloudflare Pages](#cloudflare-pages) :::note @@ -125,7 +124,7 @@ After your assets are uploaded, Wrangler will give you a preview URL to inspect ### How to deploy with CI/CD -You can also use a CI/CD system such as [Workers Builds (BETA)](https://developers.cloudflare.com/workers/ci-cd/builds/) to automatically build and deploy your site on push. +You can also use a CI/CD system such as [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) to automatically build and deploy your site on push. If you're using Workers Builds: @@ -143,144 +142,6 @@ If you're using Workers Builds: 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](https://developers.cloudflare.com/workers/wrangler/get-started/). - - - - ```sh - npm install wrangler@latest --save-dev - ``` - - - ```sh - pnpm add wrangler@latest --save-dev - ``` - - - ```sh - yarn add wrangler@latest --dev - ``` - - - -2. If your site uses on-demand rendering, install the [`@astrojs/cloudflare` adapter](/en/guides/integrations-guide/cloudflare/). - - This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step. - - - - ```sh - npx astro add cloudflare - ``` - - - ```sh - pnpm astro add cloudflare - ``` - - - ```sh - yarn astro add cloudflare - ``` - - - -3. Create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/). - - 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: - - - - ```jsonc title="wrangler.jsonc" - { - "name": "my-astro-app", - "compatibility_date": "YYYY-MM-DD", // Update to the day you deploy - "pages_build_output_dir": "./dist" - } - ``` - - - ```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" - } - ``` - - - - Read more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/). - -3. Preview your project locally with Wrangler. - - - - ```sh - npx astro build && wrangler pages dev ./dist - ``` - - - ```sh - pnpm astro build && wrangler pages dev ./dist - ``` - - - ```sh - yarn astro build && wrangler pages dev ./dist - ``` - - - -4. Deploy using `npx wrangler deploy`. - - - - ```sh - npx astro build && wrangler pages deploy ./dist - ``` - - - ```sh - pnpm astro build && wrangler pages deploy ./dist - ``` - - - ```sh - 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](https://dash.cloudflare.com/) 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 @@ -296,8 +157,6 @@ For Workers projects, you will need to set `not_found_handling` if you want to s } ``` -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](https://developers.cloudflare.com/pages/configuration/serving-pages/#single-page-application-spa-rendering) 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. From 145976b240f0eff0823e0b65471dbb072a324fd0 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Wed, 18 Mar 2026 07:16:29 +0100 Subject: [PATCH 4/6] Update src/content/docs/en/guides/deploy/cloudflare.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/deploy/cloudflare.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index 20da431e60d33..87c3d5283571d 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -15,9 +15,6 @@ 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 [Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/). -This guide includes: - -- [How to deploy to Cloudflare Workers](#cloudflare-workers) :::note From d54e8ff9b09d888bc55cb3d956d604928e28a9d8 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Wed, 18 Mar 2026 07:18:27 +0100 Subject: [PATCH 5/6] Update src/content/docs/en/guides/deploy/cloudflare.mdx --- src/content/docs/en/guides/deploy/cloudflare.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index 87c3d5283571d..bf75afc3c68fe 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -128,7 +128,7 @@ If you're using Workers Builds: 1. Follow Steps 1-3 from the Wrangler section above. -2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to `Workers & Pages`. Select `Create`. +2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to `Compute > Workers & Pages`. Select `Create`. 3. Under `Import a repository`, select a Git account and then the repository containing your Astro project. From baab2cccb4bea410d1ee7025ba3ae46b8479f19c Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Wed, 18 Mar 2026 07:19:35 +0100 Subject: [PATCH 6/6] Apply suggestion from @alexanderniebuhr --- src/content/docs/en/guides/deploy/cloudflare.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index bf75afc3c68fe..64452da0c3793 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -128,7 +128,7 @@ If you're using Workers Builds: 1. Follow Steps 1-3 from the Wrangler section above. -2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to `Compute > Workers & Pages`. Select `Create`. +2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) 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.