Add Cloudflare Astro 6 docs #12981
Add Cloudflare Astro 6 docs #12981
Conversation
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
ArmandPhilippot
left a comment
ArmandPhilippot
left a comment
There was a problem hiding this comment.
Thank you Matt, this looks great! And well done with the upgrade guide! 🙌🏽
I left a few suggestions, most of them are nits and I expect you to weight on them as Cloudflare expert and native speaker to judge if this makes sense or not. 😅
The most important thing is your formatter which is messing with the API blocks... It would be better to revert these changes.
Otherwise, this looks to be in great shape to me!
| 3. Optionally, create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings, or to declare Cloudflare bindings (KV, D1, Durable Objects, etc.): | ||
|
|
||
| ```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 | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 4. Create a `.assetsignore` file in your `public/` folder, and add the following lines to it: | ||
| ```jsonc title="wrangler.jsonc" | ||
| { | ||
| "name": "my-astro-app", | ||
| // Add your bindings here, e.g.: | ||
| // "kv_namespaces": [{ "binding": "MY_KV", "id": "<namespace_id>" }] | ||
| } | ||
| ``` | ||
|
|
||
| ```txt title="public/.assetsignore" | ||
| _worker.js | ||
| _routes.json | ||
| ``` | ||
| For simple projects without bindings, you can skip this step as Astro will generate a default configuration automatically. The Worker name will be based on the `package.json` name field or the folder name. |
There was a problem hiding this comment.
Sorry, I can't make a suggestion directly because GitHub is not happy with deleted lines. This step looks fine to me, but I wonder if it wouldn't be more helpful to talk about the default value first to emphasize that this is optional and help users determine whether they need it or not before reading further.
What I was thinking is something like:
- Astro will automatically generate a default configuration by reusing the
package.jsonname field or the folder name as Worker name. You can optionally create a Wrangler configuration file to define custom settings. The following example declares Cloudflare KV bindings:
Then, we don't need the paragraph below the code snippet. And, we could uncomment the code in the code snippet.
| <p> | ||
| **Type:** `boolean`<br /> | ||
| **Default:** `true` | ||
| **Type:** `boolean` |
There was a problem hiding this comment.
I assume this is auto formatting (here and in other places), but it makes tracking changes more difficult. This will also affect translators when checking what actually changed here. And, more important, this breaks the formatting:
| Before | After |
|---|---|
 |
 |
| </p> | ||
|
|
||
| The `sessionKVBindingName` option allows you to specify the name of the KV binding used for session storage. By default, this is set to `SESSION`, but you can change it to match your own KV binding name. See [Sessions](#sessions) for more information. | ||
| Sets the name of the KV binding used for session storage. The KV namespace is automatically provisioned when you deploy. By default, the binding is named `SESSION`, but you can change it if you define the binding manually in your wrangler config. See [Sessions](#sessions) for more information. |
There was a problem hiding this comment.
I like the rewording at the beginning of the sentence!
But, maybe it's just me, while reading I feel that "The KV namespace is automatically provisioned when you deploy." breaks a bit the flow. I'm not familiar enough with Cloudflare (+ probably the language barrier) to suggest something accurate I think. Does the following make sense, or was putting it outside of "By default" intentional?
| Sets the name of the KV binding used for session storage. The KV namespace is automatically provisioned when you deploy. By default, the binding is named `SESSION`, but you can change it if you define the binding manually in your wrangler config. See [Sessions](#sessions) for more information. | |
| Sets the name of the KV binding used for session storage. By default, the KV namespace is automatically provisioned when you deploy and the binding is named `SESSION`. You can change this name by setting the binding manually in your wrangler config. See [Sessions](#sessions) for more information. |
| The path to the entry file. This should be a relative path from the root of your Astro project. | ||
|
|
||
| By default, the adapter uses a generic entry file, which only supports the `fetch` handler. | ||
| Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. The binding is automatically provisioned when you deploy. By default, the binding is named `IMAGES`, but you can change it if you define the binding manually in your wrangler config. |
There was a problem hiding this comment.
If my previous comment makes sense, I have the same feeling here with "The binding is automatically provisioned when you deploy.".
| Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. The binding is automatically provisioned when you deploy. By default, the binding is named `IMAGES`, but you can change it if you define the binding manually in your wrangler config. | |
| Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. By default, the binding is automatically provisioned when you deploy and the binding is named `IMAGES`. You can change it by setting the binding manually in your wrangler config: |
But then, I wonder if reversing the two code snippets wouldn't be more logical.
| Environment variables and bindings defined in your `wrangler.jsonc` configuration file are accessed by importing `env` from `cloudflare:workers`: | ||
|
|
||
| ```astro title="src/pages/index.astro" | ||
| --- | ||
| const { env } = Astro.locals.runtime; | ||
| --- | ||
| ``` | ||
| You can access the runtime from API endpoints through `context.locals`: | ||
| import { env } from 'cloudflare:workers'; | ||
| ```js title="src/pages/api/someFile.js" | ||
| export function GET(context) { | ||
| const runtime = context.locals.runtime; | ||
|
|
||
| return new Response('Some body'); | ||
| } | ||
| const myVariable = env.MY_VARIABLE; | ||
| const myKVNamespace = env.MY_KV; | ||
| --- | ||
| ``` | ||
|
|
||
| See the [list of all supported bindings](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings) in the Cloudflare documentation. | ||
|
|
||
|
|
||
| ### Environment variables and secrets | ||
|
|
||
| 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.jsonc` as follows: | ||
| Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) in `wrangler.jsonc`: | ||
|
|
||
| ```jsonc title="wrangler.jsonc" | ||
| { | ||
| "vars" : { | ||
| "MY_VARIABLE": "test" | ||
| } | ||
| "vars": { | ||
| "MY_VARIABLE": "test", | ||
| }, | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Again, I can't make a proper suggestion here, but regarding the flow, I wonder if it wouldn't be more logical to show first how to define them, then how to access them, rather than the other way around:
[Environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) and bindings are defined in your `wrangler.jsonc` configuration file:
/* code snippet */
You can then access them by importing `env` from `cloudflare:workers`:
/* code snippet */
| ``` | ||
| ```astro title="src/components/CartButton.astro" | ||
| --- | ||
| export const prerender = false; |
There was a problem hiding this comment.
I see this is not new, but we now tend to add a comment alongside this:
| export const prerender = false; | |
| export const prerender = false; // Not needed in 'server' mode |
| ## Node.js compatibility | ||
|
|
||
| Out of the box, Cloudflare does not support the Node.js runtime APIs. With some configuration, Cloudflare does support a subset of the Node.js runtime APIs. You can find supported Node.js runtime APIs in Cloudflare's [documentation](https://developers.cloudflare.com/workers/runtime-apis/nodejs). | ||
| Cloudflare Workers supports a growing subset of Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. |
There was a problem hiding this comment.
nit: I feel like "growing" might be a bit too marketing speech and might not have its place here? Or, with a link to a roadmap or something, I guess it could make sense:
| Cloudflare Workers supports a growing subset of Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. | |
| Cloudflare Workers supports a subset of Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation. |
| Then use the `node:*` import syntax in your server-side code: | ||
|
|
||
| ```js title="src/pages/api/endpoint.js" | ||
| export const prerender = false; |
There was a problem hiding this comment.
Same as before, since we're updating anyway, I think we can add this while we're at it:
| export const prerender = false; | |
| export const prerender = false; // Not needed in 'server' mode |
|
|
||
| ### Meaningful error messages | ||
|
|
||
| Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: |
There was a problem hiding this comment.
While this is honest, maybe we could only say:
| Currently, errors during running your application in Wrangler are not very useful, due to the minification of your code. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: | |
| By default, errors occurring while running your application in Wrangler are minified. For better debugging, add `vite.build.minify = false` to your `astro.config.mjs`: |
| export default defineConfig({ | ||
| adapter: cloudflare(), | ||
| build: { | ||
| client: './dist', |
There was a problem hiding this comment.
| client: './dist', | |
| client: './', |
This value is relative to the outDir setting, so it should not include dist
| adapter: cloudflare(), | ||
| build: { | ||
| client: './dist', | ||
| server: './dist/_worker.js', |
There was a problem hiding this comment.
| server: './dist/_worker.js', | |
| server: './_worker.js', |
This value is relative to the outDir setting, so it should not include dist
Description (required)
This PR updates the Cloudflare integration guide to use the new Astro 6 APIs. It also adds a migration guide for users moving from Astro 5 to 6. It includes some info about manually configuring Cloudflare Pages (which is no longer automatic), but it doesn't yet have a very good guide to migrate from Pages to Workers. It links out to the guide in the Cloudflare docs, but I'd like to add something more Astro-specific in a follow-up PR.
Related issues & labels (optional)