Skip to content

remove CF Pages workaround #13466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexanderniebuhr merged 7 commits into from
Mar 18, 2026
Merged

remove CF Pages workaround #13466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7046fb9
remove CF Pages workaround
alexanderniebuhr Mar 14, 2026
edb8a30
apply suggestion
alexanderniebuhr Mar 17, 2026
b41b02d
Merge branch 'main' into remove-cf-pages-workaround
alexanderniebuhr Mar 17, 2026
9bf1783
update deploy guide
alexanderniebuhr Mar 17, 2026
145976b
Update src/content/docs/en/guides/deploy/cloudflare.mdx
alexanderniebuhr Mar 18, 2026
d54e8ff
Update src/content/docs/en/guides/deploy/cloudflare.mdx
alexanderniebuhr Mar 18, 2026
baab2cc
Apply suggestion from @alexanderniebuhr
alexanderniebuhr Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 3 additions & 147 deletions src/content/docs/en/guides/deploy/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,8 @@ 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

Expand Down Expand Up @@ -125,14 +121,14 @@ 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:

<Steps>
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 application`.

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

Expand All @@ -143,144 +139,6 @@ If you're using Workers Builds:
5. Click `Save and Deploy`. You can now preview your Worker at its provided `workers.dev` subdomain.
</Steps>

## Cloudflare Pages

### How to deploy with Wrangler

<Steps>
1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/).

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add wrangler@latest --save-dev
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add wrangler@latest --dev
```
</Fragment>
</PackageManagerTabs>

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.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro add cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro add cloudflare
```
</Fragment>
</PackageManagerTabs>

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:

<StaticSsrTabs>
<Fragment slot="static">
```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"pages_build_output_dir": "./dist"
}
```
</Fragment>
<Fragment slot="ssr">
```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"
}
```
</Fragment>
</StaticSsrTabs>

<ReadMore>Read more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/).</ReadMore>

3. Preview your project locally with Wrangler.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages dev ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages dev ./dist
```
</Fragment>
</PackageManagerTabs>

4. Deploy using `npx wrangler deploy`.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npx astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro build && wrangler pages deploy ./dist
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn astro build && wrangler pages deploy ./dist
```
</Fragment>
</PackageManagerTabs>
</Steps>

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

### How to deploy a site with CI/CD

<Steps>
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.
</Steps>

## Troubleshooting

### 404 behavior
Expand All @@ -296,8 +154,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.
Expand Down
43 changes: 2 additions & 41 deletions src/content/docs/en/guides/integrations-guide/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

<Steps>
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.
</Steps>

## 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.
Expand Down Expand Up @@ -677,14 +640,12 @@ 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.

<ReadMore>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.</ReadMore>

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.
Expand Down
Loading