From 6b021b4fee390f241a6b8cdbeb3a10ee19d58391 Mon Sep 17 00:00:00 2001 From: korinne Date: Mon, 24 Mar 2025 17:22:22 -0700 Subject: [PATCH 01/13] updates framework guide for Astro on Workers --- .../frameworks/framework-guides/astro.mdx | 115 +++++++++++++----- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index edf37d5e79c2957..66b372b7a2e1cc6 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -6,64 +6,117 @@ description: Create an Astro application and deploy it to Cloudflare Workers wit --- import { + Aside, Badge, + Details, + Steps, + WranglerConfig, Description, InlineBadge, Render, + TabItem, + Tabs, PackageManagers, } from "~/components"; -In this guide, you will create a new [Astro](https://astro.build/) application and deploy to Cloudflare Workers (with the new [ Workers Assets](/workers/static-assets/)). + -```sh -cd my-astro-app -``` +## What is Astro? -## 2. Develop locally +[Astro](https://astro.build/) is a web framework built with JavaScript and designed for creating websites that display large amounts of content (such as blogs, documentation sites, or online stores). Astro emphasizes performance through minimal client-side JavaScript, as well as other [design principles](https://docs.astro.build/en/concepts/why-astro/#design-principles). By default, it renders most content on the server, and only the parts of a page requiring interactivity are shipped to the browser. See [Key features](/workers/frameworks/framework-guides/astro/#astros-key-features) for more information about Astro, and check out their [integrations](https://astro.build/integrations/) to see how to add functionality from community integrations. -After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development. +## Astro's Key features - +#### On-demand rendering -## 3. Deploy your Project +Astro lets you decide how and when your pages, routes, and API endpoints are rendered. [By default](https://docs.astro.build/en/guides/on-demand-rendering/), Astro pre-renders everything at build time, generating static files for fast delivery. However, you can also render some or all routes [on demand with server-side rendering (SSR)](https://docs.astro.build/en/guides/on-demand-rendering/#server-adapters). This means pages are generated dynamically on the server when a request is made, allowing you to serve personalized or frequently changing content without sacrificing performance on other static pages. -Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/). +#### Zero JS, by default -The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately. +Astro’s [default behavior](https://docs.astro.build/en/basics/astro-components/) is to send **no** JavaScript to the browser. Instead, it renders components to HTML either at build time or on demand, instead of on the client. Any unnecessary JavaScript is stripped away before the final page is sent to the browser, keeping the JavaScript footprint to zero. - +#### Islands ---- +Most of an Astro page is delivered as static HTML, with small [“islands”](https://docs.astro.build/en/concepts/islands/) of JavaScript added only where interactivity or personalization is needed. These can be client or server islands: + +- [**Client islands**](https://docs.astro.build/en/concepts/islands/#client-islands) run in the browser and handle interactive features. +- [**Server islands**](https://docs.astro.build/en/concepts/islands/#server-islands) can offload certain computations or data fetching to the server, minimizing client work. + +#### UI-agnostic + +Astro is **framework-agnostic**, and supports every major UI framework, including React, Preact, Svelte, Vue, SolidJS , via its official [integrations](https://astro.build/integrations/). + +## Deploy a new Astro project on Workers + + +1. **Create a new project with the create-cloudflare CLI (C3).** + + +
+ When you run this command, C3 creates a new project directory, initiates [Astro's official setup tool](https://docs.astro.build/en/tutorial/1-setup/2/), and provides the option to deploy instantly. +
+ +2. **Develop locally.** + + After creating your project, run the following command in your project directory to start a local development server. + + + +3. **Deploy your project.** + + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. + + + + + +## Deploy an existing Astro project on Workers + + +1. **Install the Astro adapter.** + + +
+ This command installs the adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. You can read more about the adapter configuration options [here](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options). +
-## Bindings +2. **Build your project.** -Your Astro application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Astro documentation](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#cloudflare-runtime) provides information about configuring bindings and how you can access them in your `locals`. + -## Static assets +3. **Deploy your project.** -You can serve static assets your Astro application by placing them in [the `./public/` directory](https://docs.astro.build/en/basics/project-structure/#public). This can be useful for resource files such as images, stylesheets, fonts, and manifests. + - + From 86c6f6e64bba9669299c67de27fa1912fec593dc Mon Sep 17 00:00:00 2001 From: korinne <40270578+korinne@users.noreply.github.com> Date: Tue, 25 Mar 2025 08:38:17 -0700 Subject: [PATCH 02/13] Update src/content/docs/workers/frameworks/framework-guides/astro.mdx Co-authored-by: Pete Bacon Darwin --- src/content/docs/workers/frameworks/framework-guides/astro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 66b372b7a2e1cc6..795d272c0b18302 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -108,7 +108,7 @@ Astro is **framework-agnostic**, and supports every major UI framework, includin />
- This command installs the adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. You can read more about the adapter configuration options [here](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options). + This command installs the Cloudflare adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. You can read more about the adapter configuration options [here](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options).
2. **Build your project.** From 0c1460e97fc97fecb4808966c2926abeef3ec2c9 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Wed, 26 Mar 2025 19:08:30 +0000 Subject: [PATCH 03/13] simplify introduction --- .../frameworks/framework-guides/astro.mdx | 23 +++---------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 795d272c0b18302..77808871fb33391 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -46,28 +46,11 @@ Scaffold an Astro project on Workers, and pick your template. ## What is Astro? -[Astro](https://astro.build/) is a web framework built with JavaScript and designed for creating websites that display large amounts of content (such as blogs, documentation sites, or online stores). Astro emphasizes performance through minimal client-side JavaScript, as well as other [design principles](https://docs.astro.build/en/concepts/why-astro/#design-principles). By default, it renders most content on the server, and only the parts of a page requiring interactivity are shipped to the browser. See [Key features](/workers/frameworks/framework-guides/astro/#astros-key-features) for more information about Astro, and check out their [integrations](https://astro.build/integrations/) to see how to add functionality from community integrations. +[Astro](https://astro.build/) is a JavaScript web framework designed for creating websites that display large amounts of content (such as blogs, documentation sites, or online stores). -## Astro's Key features +Astro emphasizes performance through minimal client-side JavaScript - by default, it renders as much content as possible at build time, or (on-demand)[https://docs.astro.build/en/guides/on-demand-rendering/] on the "server" - this can be a Cloudflare Worker. [“Islands”](https://docs.astro.build/en/concepts/islands/) of JavaScript are added only where interactivity or personalization is needed. -#### On-demand rendering - -Astro lets you decide how and when your pages, routes, and API endpoints are rendered. [By default](https://docs.astro.build/en/guides/on-demand-rendering/), Astro pre-renders everything at build time, generating static files for fast delivery. However, you can also render some or all routes [on demand with server-side rendering (SSR)](https://docs.astro.build/en/guides/on-demand-rendering/#server-adapters). This means pages are generated dynamically on the server when a request is made, allowing you to serve personalized or frequently changing content without sacrificing performance on other static pages. - -#### Zero JS, by default - -Astro’s [default behavior](https://docs.astro.build/en/basics/astro-components/) is to send **no** JavaScript to the browser. Instead, it renders components to HTML either at build time or on demand, instead of on the client. Any unnecessary JavaScript is stripped away before the final page is sent to the browser, keeping the JavaScript footprint to zero. - -#### Islands - -Most of an Astro page is delivered as static HTML, with small [“islands”](https://docs.astro.build/en/concepts/islands/) of JavaScript added only where interactivity or personalization is needed. These can be client or server islands: - -- [**Client islands**](https://docs.astro.build/en/concepts/islands/#client-islands) run in the browser and handle interactive features. -- [**Server islands**](https://docs.astro.build/en/concepts/islands/#server-islands) can offload certain computations or data fetching to the server, minimizing client work. - -#### UI-agnostic - -Astro is **framework-agnostic**, and supports every major UI framework, including React, Preact, Svelte, Vue, SolidJS , via its official [integrations](https://astro.build/integrations/). +Astro is also framework-agnostic, and supports every major UI framework, including React, Preact, Svelte, Vue, SolidJS , via its official [integrations](https://astro.build/integrations/). ## Deploy a new Astro project on Workers From 1bf01794144785b6330782c71547275964f17309 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Wed, 26 Mar 2025 19:08:51 +0000 Subject: [PATCH 04/13] update migration guides --- .../frameworks/framework-guides/astro.mdx | 110 +++++++++++++++--- 1 file changed, 95 insertions(+), 15 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 77808871fb33391..60b79434ded0d30 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -63,7 +63,8 @@ Astro is also framework-agnostic, and supports every major UI framework, includi />
- When you run this command, C3 creates a new project directory, initiates [Astro's official setup tool](https://docs.astro.build/en/tutorial/1-setup/2/), and provides the option to deploy instantly. + When you run this command, C3 creates a new project directory, initiates [Astro's official setup tool](https://docs.astro.build/en/tutorial/1-setup/2/), and configures the project for Cloudflare. It then offers the option to instantly deploy your application to Cloudflare. +
2. **Develop locally.** @@ -82,24 +83,103 @@ Astro is also framework-agnostic, and supports every major UI framework, includi ## Deploy an existing Astro project on Workers - -1. **Install the Astro adapter.** - +### If you have a static site -
- This command installs the Cloudflare adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. You can read more about the adapter configuration options [here](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options). +If your Astro project is a purely static site, follow these steps: + + +1. Add a Wrangler configuration file + In your project root, create a Wrangler configuration file with the following content: + + + + ```json + { + "name": "my-astro-app", + // Update to today's date + "compatibility_date": "2025-03-25", + "assets": { + "directory": "./dist" + } + } + ``` + + +
+ The key part of this config is the `assets` field, which tells Wrangler where to find your static assets. In this case, we're telling Wrangler to look in the `./dist` directory. If your assets are in a different directory, update the `directory` value accordingly. + Read about other [asset configuration options](/workers/static-assets/routing/).
-2. **Build your project.** +2. **Deploy your project.** + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. + - + -3. **Deploy your project.** +### If your site uses server rendering - +If your Astro project uses [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/), follow these steps: - + +1. **Install the Astro Cloudflare adapter.** + + +
+ This command installs the Cloudflare adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. By default, this sets the build output configuration to `output: 'server'`, which server renders all your pages by default. If there are certain pages that *don't* need server-sider rendering, for example static pages like a privacy policy, you should set `export const prerender = true` for that page or route to pre-render it. You can read more about the adapter configuration options [in the Astro docs](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options). +
+ +2. **Add a Wrangler configuration file** + + In your project root, create a Wrangler configuration file with the following content: + + + ```json + { + "name": "my-astro-app", + "main": "./dist/_worker.js/index.js", + // Update to today's date + "compatibility_date": "2025-03-25", + "compatibility_flags": ["nodejs_compat"], + "assets": { + "binding": "ASSETS", + "directory": "./dist" + }, + "observability": { + "enabled": true + } + } + ``` + +
+ The key parts of this config are: + - `main` points to the entry point of your Worker script. This is generated by the Astro adaptor, and is what powers your server-rendered pages. + - `assets.directory` tells Wrangler where to find your static assets. In this case, we're telling Wrangler to look in the `./dist` directory. If your assets are in a different directory, update the `directory` value accordingly. + + Read more about [Wrangler configuration options](/workers/wrangler/configuration/) and [asset configuration options](/workers/static-assets/routing/). +
+ +3. **Build and deploy your project** + + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. + + + + + + +## Bindings + +:::note +You cannot use bindings if you're using Astro to generate a purely static site. +::: +Astro applications can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using [bindings](/workers/runtime-apis/bindings/). The [Astro docs](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#cloudflare-runtime) provide information about how you can access them in your `locals`. + +## Astro's build configuration + +The Astro Cloudflare adapter sets the build output configuration to `output: 'server'`, which means all pages are rendered on-demand in your Cloudflare Worker. If there are certain pages that _don't_ need server-sider rendering, for example static pages such as a privacy policy, you should set `export const prerender = true` for that page or route to pre-render it. You can read more about on-demand rendering [in the Astro docs](https://docs.astro.build/en/guides/on-demand-rendering/). + +If you want to use Astro as a static site generator, you do not need the Astro Cloudflare adapter. Astro will pre-render all pages at build time by default, and you can simply upload those static assets to be served by Cloudflare. From aaaae80232583ea4aa26b9933c9fae3f68cb369e Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Wed, 26 Mar 2025 19:54:31 +0000 Subject: [PATCH 05/13] forgot build step --- .../docs/workers/frameworks/framework-guides/astro.mdx | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 60b79434ded0d30..61ed208159134e1 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -110,9 +110,12 @@ If your Astro project is a purely static site, follow these steps: Read about other [asset configuration options](/workers/static-assets/routing/).
-2. **Deploy your project.** - You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. - +2. **Build and deploy your project** + + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. + + + From bce737f1ccc05c8041254861172ef3268fc0fcbb Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 27 Mar 2025 14:19:48 +0000 Subject: [PATCH 06/13] fix headings --- .../docs/workers/frameworks/framework-guides/astro.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 61ed208159134e1..4086d637eb08efd 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -88,7 +88,8 @@ Astro is also framework-agnostic, and supports every major UI framework, includi If your Astro project is a purely static site, follow these steps: -1. Add a Wrangler configuration file +1. **Add a Wrangler configuration file** + In your project root, create a Wrangler configuration file with the following content: @@ -124,7 +125,7 @@ If your Astro project is a purely static site, follow these steps: If your Astro project uses [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/), follow these steps: -1. **Install the Astro Cloudflare adapter.** +1. **Install the Astro Cloudflare adapter** Date: Thu, 27 Mar 2025 14:20:02 +0000 Subject: [PATCH 07/13] get rid of tabs --- .../frameworks/framework-guides/astro.mdx | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 4086d637eb08efd..6e86870e4f6584d 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -21,17 +21,7 @@ import { From 8ae667704ccb0a4805cc44a981ceec9a5c21f32b Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 27 Mar 2025 14:21:33 +0000 Subject: [PATCH 08/13] change wording a bit? --- src/content/docs/workers/frameworks/framework-guides/astro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 6e86870e4f6584d..417ffdb59b2d7e3 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -78,7 +78,7 @@ Astro is also framework-agnostic, and supports every major UI framework, includi ### If you have a static site -If your Astro project is a purely static site, follow these steps: +If your Astro project is entirely pre-rendered, follow these steps: 1. **Add a Wrangler configuration file** From 3ebbf0c299dd93b27db738f3a1e98fe5e9c13ee2 Mon Sep 17 00:00:00 2001 From: emily-shen <69125074+emily-shen@users.noreply.github.com> Date: Thu, 27 Mar 2025 17:37:17 +0000 Subject: [PATCH 09/13] remove aside --- .../docs/workers/frameworks/framework-guides/astro.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/astro.mdx b/src/content/docs/workers/frameworks/framework-guides/astro.mdx index 417ffdb59b2d7e3..6fb4892045d5bce 100644 --- a/src/content/docs/workers/frameworks/framework-guides/astro.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/astro.mdx @@ -6,7 +6,6 @@ description: Create an Astro application and deploy it to Cloudflare Workers wit --- import { - Aside, Badge, Details, Steps, @@ -19,8 +18,6 @@ import { PackageManagers, } from "~/components"; -