Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat: update cloudflare docs #12603

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
Parent: 5.15.0 minor release docs
merged 18 commits into from
Oct 23, 2025
Merged

feat: update cloudflare docs #12603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
cb86cda
feat: update cloudflare docs
florian-lefebvre Oct 22, 2025
309dbdc
update cloudflare pages section of deploy guide to instruct user to c…
OliverSpeir Oct 22, 2025
7773d9c
Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx
florian-lefebvre Oct 22, 2025
b8dbfb7
Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx
florian-lefebvre Oct 22, 2025
ce3aa73
Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx
florian-lefebvre Oct 22, 2025
b483700
update the deploy steps, and add 404 section
OliverSpeir Oct 22, 2025
dda4108
add comma
OliverSpeir Oct 22, 2025
d8dc443
Update cloudflare.mdx
florian-lefebvre Oct 22, 2025
4049735
Update cloudflare.mdx
OliverSpeir Oct 22, 2025
7a61fce
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
4c14520
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
2cfb4e6
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
38001c1
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
743641c
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
c241402
Update src/content/docs/en/guides/deploy/cloudflare.mdx
OliverSpeir Oct 22, 2025
f79febb
Armand consistency fixes
sarah11918 Oct 23, 2025
40c3c28
Merge branch 'main' into feat/update-cloudflare-install-docs
sarah11918 Oct 23, 2025
8aab860
Merge branch '5.15.0' into feat/update-cloudflare-install-docs
sarah11918 Oct 23, 2025
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
184 changes: 147 additions & 37 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 @@ -9,6 +9,7 @@ i18nReady: true
import ReadMore from '~/components/ReadMore.astro';
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/).

Expand Down Expand Up @@ -41,50 +42,57 @@ To get started, you will need:
npm install wrangler@latest --save-dev
```

2. If your site uses on demand rendering, install the [`@astrojs/cloudflare` adapter](/en/guides/integrations-guide/cloudflare/).
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.

```bash

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

Then, create a `.assetsignore` file in your `public/` folder, and add the following lines to it:
```txt title="public/.assetsignore"
_worker.js
_routes.json
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm astro add cloudflare
```

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

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

3. Create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).

Running `astro add cloudflare` will create this for you; if you are not using the adapter, you'll need to create it yourself.

<StaticSsrTabs>
<Fragment slot="static">
```jsonc
// wrangler.jsonc
```jsonc title="wrangler.jsonc"
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-astro-app",
// Update to today's date
"compatibility_date": "2025-03-25",
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"assets": {
"binding": "ASSETS",
"directory": "./dist",
"not_found_handling": "404-page" // If you have a custom `src/pages/404.astro` page
}
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc
// wrangler.jsonc
```jsonc title="wrangler.jsonc"
{
"$schema": "node_modules/wrangler/config-schema.json",
"main": "dist/_worker.js/index.js",
"name": "my-astro-app",
"main": "./dist/_worker.js/index.js",
// Update to today's date
"compatibility_date": "2025-03-25",
"compatibility_flags": ["nodejs_compat"],
"compatibility_date": "YYYY-MM-DD", // Update to the day you deploy
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": "./dist"
Expand Down Expand Up @@ -141,36 +149,123 @@ If you're using Workers Builds:
<Steps>
1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/).

```bash
npm install wrangler@latest --save-dev
```
<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/).
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.

```bash
npx astro add cloudflare
<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"
}
```

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

```bash
npx astro build && npx wrangler pages dev ./dist
```
<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`.

```bash
npx astro build && npx wrangler pages deploy ./dist
```
<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 Git
### How to deploy a site with CI/CD

<Steps>
1. Push your code to your git repository (e.g. GitHub, GitLab).
Expand All @@ -187,6 +282,21 @@ After your assets are uploaded, Wrangler will give you a preview URL to inspect

## Troubleshooting

### 404 behavior

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](https://developers.cloudflare.com/workers/static-assets/#routing-behavior) of Cloudflare's documentation.

```jsonc title="wrangler.jsonc"
{
"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](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
Loading