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
sarah11918 merged 18 commits into from
Oct 23, 2025
Merged

feat: update cloudflare docs #12603

Show file tree
Hide file tree
Changes from 4 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
137 changes: 109 additions & 28 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 @@ -44,44 +45,51 @@ To get started, you will need:
2. If your site uses on demand rendering, install the [`@astrojs/cloudflare` adapter](/en/guides/integrations-guide/cloudflare/).
Comment thread
OliverSpeir marked this conversation as resolved.
Outdated

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/).
3. Update your [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).
Comment thread
OliverSpeir marked this conversation as resolved.
Outdated

<StaticSsrTabs>
<Fragment slot="static">
```jsonc
// wrangler.jsonc
```jsonc title="wrangler.jsonc" ins={9-10}
{
"$schema": "node_modules/wrangler/config-schema.json",
"main": "dist/_worker.js/index.js",
"name": "my-astro-app",
// Update to today's date
"compatibility_date": "2025-03-25",
"assets": {
"binding": "ASSETS",
"directory": "./dist",
"not_found_handling": "404-page" // If you have a custom `src/pages/404.astro` page
// If you have a custom `src/pages/404.astro` page
"not_found_handling": "404-page"
}
}
```
</Fragment>
<Fragment slot="ssr">
```jsonc
// wrangler.jsonc
```jsonc title="wrangler.jsonc" ins={6,11-13}
{
"$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"],
Expand Down Expand Up @@ -141,31 +149,104 @@ 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/).
Comment thread
OliverSpeir marked this conversation as resolved.
Outdated

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>


Because Cloudflare recommends new projects to 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.
Comment thread
OliverSpeir marked this conversation as resolved.
Outdated

Change your `wrangler.jsonc` file to be structured like this:

```jsonc title="wrangler.jsonc"
{
"name": "my-astro-app",
"compatibility_date": "YYYY-MM-DD",
"compatibility_flags": [
"nodejs_compat",
"disable_nodejs_process_v2"
],
"pages_build_output_dir": "./dist"
}
Comment thread
OliverSpeir marked this conversation as resolved.
```

<ReadMore>Read more about [on demand rendering in Astro](/en/guides/on-demand-rendering/).</ReadMore>
Comment thread
OliverSpeir marked this conversation as resolved.
Outdated

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.
Expand Down
100 changes: 66 additions & 34 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 @@ -9,12 +9,11 @@ category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';


This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Cloudflare](https://www.cloudflare.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/).

If you're using Astro as a static site builder, you don't need an adapter.
Expand Down Expand Up @@ -54,36 +53,69 @@ Now, you can enable [on-demand rendering per page](/en/guides/on-demand-renderin

### Manual Install

First, add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager.
<Steps>

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install @astrojs/cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add @astrojs/cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add @astrojs/cloudflare
```
</Fragment>
</PackageManagerTabs>
1. Add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager.

<PackageManagerTabs>
<Fragment slot="npm">
```sh
npm install @astrojs/cloudflare
```
</Fragment>
<Fragment slot="pnpm">
```sh
pnpm add @astrojs/cloudflare
```
</Fragment>
<Fragment slot="yarn">
```sh
yarn add @astrojs/cloudflare
```
</Fragment>
</PackageManagerTabs>

2. Add the adapter to your `astro.config.mjs` file:

```js title="astro.config.mjs" ins={2,5}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
adapter: cloudflare(),
});
```

Then, add the adapter to your `astro.config.mjs` file:
3. Create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/):
Comment thread
florian-lefebvre marked this conversation as resolved.

```json title="wrangler.jsonc"
Comment thread
florian-lefebvre marked this conversation as resolved.
Outdated
{
"main": "dist/_worker.js/index.js",
"name": "my-astro-app",
// Update to today's date
"compatibility_date": "2025-03-25",
"compatibility_flags": [
"nodejs_compat",
"global_fetch_strictly_public"
],
"assets": {
"binding": "ASSETS",
"directory": "./dist"
},
"observability": {
"enabled": true
}
}
Comment thread
florian-lefebvre marked this conversation as resolved.
```

```js title="astro.config.mjs" ins={2,5}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
4. Create a `.assetsignore` file in your `public/` folder, and add the following lines to it:

export default defineConfig({
adapter: cloudflare(),
});
```
```txt title="public/.assetsignore"
_worker.js
_routes.json
```

</Steps>

## Options

Expand Down Expand Up @@ -344,7 +376,7 @@ export function createExports(manifest: SSRManifest) {
### Usage

The Cloudflare runtime gives you access to environment variables and bindings to Cloudflare resources.
The Cloudflare runtime uses bindings found in the `wrangler.toml`/`wrangler.json` configuration file.
The Cloudflare runtime uses bindings found in the `wrangler.toml`/`wrangler.jsonc` configuration file.
Comment thread
florian-lefebvre marked this conversation as resolved.
Outdated

You can access the bindings from `Astro.locals.runtime`:

Expand All @@ -370,9 +402,9 @@ See the [list of all supported bindings](https://developers.cloudflare.com/worke

The Cloudflare runtime treats environment variables as a type of binding.

For example, you can define an [environment variable](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.json` as follows:
For example, you can define an [environment variable](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc` as follows:

```json title="wrangler.json"
```json title="wrangler.jsonc"
Comment thread
sarah11918 marked this conversation as resolved.
Outdated
{
"vars" : {
"MY_VARIABLE": "test"
Expand Down Expand Up @@ -498,8 +530,8 @@ Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv
2. Declare the KV namespace in your Wrangler config, setting the namespace ID to the one returned by the previous command:

<Tabs>
<TabItem label="wrangler.json">
```json title="wrangler.json" "<KV_NAMESPACE_ID>"
<TabItem label="wrangler.jsonc">
```json title="wrangler.jsonc" "<KV_NAMESPACE_ID>"
{
"kv_namespaces": [
{
Expand Down Expand Up @@ -605,7 +637,7 @@ To use [`wrangler`](https://developers.cloudflare.com/workers/wrangler/) to run
For Workers:

```json title="package.json"
"preview": "wrangler dev ./dist"
"preview": "wrangler dev"
```

For Pages:
Expand Down
Loading