diff --git a/src/content/docs/en/guides/deploy/cloudflare.mdx b/src/content/docs/en/guides/deploy/cloudflare.mdx index d34a29ed6743b..2522584ddaa84 100644 --- a/src/content/docs/en/guides/deploy/cloudflare.mdx +++ b/src/content/docs/en/guides/deploy/cloudflare.mdx @@ -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/). @@ -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 + + + + ```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 + + + ```sh + pnpm astro add cloudflare ``` - + + + ```sh + yarn astro add cloudflare + ``` + + + Read more about [on-demand rendering in Astro](/en/guides/on-demand-rendering/). 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. + - ```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 } } ``` - ```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" @@ -141,36 +149,123 @@ If you're using Workers Builds: 1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/). - ```bash - npm install wrangler@latest --save-dev - ``` + + + ```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/). +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 + + + ```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" + } ``` - - Read more about [on demand rendering in Astro](/en/guides/on-demand-rendering/). + + + ```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. - ```bash - npx astro build && npx wrangler pages dev ./dist - ``` + + + ```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`. - ```bash - npx astro build && npx wrangler pages deploy ./dist - ``` + + + ```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 Git +### How to deploy a site with CI/CD 1. Push your code to your git repository (e.g. GitHub, GitLab). @@ -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. diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 7d64dce226784..60dd13a2e518b 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -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. @@ -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. + - - - ```sh - npm install @astrojs/cloudflare - ``` - - - ```sh - pnpm add @astrojs/cloudflare - ``` - - - ```sh - yarn add @astrojs/cloudflare - ``` - - +1. Add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager. + + + + ```sh + npm install @astrojs/cloudflare + ``` + + + ```sh + pnpm add @astrojs/cloudflare + ``` + + + ```sh + yarn add @astrojs/cloudflare + ``` + + + +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/): + + ```jsonc title="wrangler.jsonc" + { + "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 + } + } + ``` -```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 + ``` + + ## Options @@ -343,8 +375,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 gives you access to environment variables and bindings to Cloudflare resources defined in your `wrangler.toml`/`wrangler.jsonc` configuration file. You can access the bindings from `Astro.locals.runtime`: @@ -370,9 +401,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" +```jsonc title="wrangler.jsonc" { "vars" : { "MY_VARIABLE": "test" @@ -498,8 +529,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: - - ```json title="wrangler.json" "" + + ```json title="wrangler.jsonc" "" { "kv_namespaces": [ { @@ -605,7 +636,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: