Skip to content

Commit 1bf0179

Browse files
emily-shenemily-shen
committed
update migration guides
1 parent 0c1460e commit 1bf0179

File tree

1 file changed

+95
-15
lines changed
  • src/content/docs/workers/frameworks/framework-guides

1 file changed

+95
-15
lines changed

‎src/content/docs/workers/frameworks/framework-guides/astro.mdx‎

Lines changed: 95 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@ Astro is also framework-agnostic, and supports every major UI framework, includi
6363
/>
6464

6565
<Details header="What's happening behind the scenes?">
66-
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.
66+
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.
67+
6768
</Details>
6869

6970
2. **Develop locally.**
@@ -82,24 +83,103 @@ Astro is also framework-agnostic, and supports every major UI framework, includi
8283

8384
## Deploy an existing Astro project on Workers
8485

85-
<Steps>
86-
1. **Install the Astro adapter.**
87-
<PackageManagers
88-
type="exec"
89-
pkg="astro"
90-
args="add cloudflare"
91-
/>
86+
### If you have a static site
9287

93-
<Details header="What's happening behind the scenes?">
94-
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).
88+
If your Astro project is a purely static site, follow these steps:
89+
90+
<Steps>
91+
1. Add a Wrangler configuration file
92+
In your project root, create a Wrangler configuration file with the following content:
93+
94+
<WranglerConfig>
95+
96+
```json
97+
{
98+
"name": "my-astro-app",
99+
// Update to today's date
100+
"compatibility_date": "2025-03-25",
101+
"assets": {
102+
"directory": "./dist"
103+
}
104+
}
105+
```
106+
107+
</WranglerConfig>
108+
<Details header="What's this configuration doing?">
109+
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.
110+
Read about other [asset configuration options](/workers/static-assets/routing/).
95111
</Details>
96112

97-
2. **Build your project.**
113+
2. **Deploy your project.**
114+
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.
115+
<PackageManagers type="exec" pkg="wrangler@latest" args="deploy" />
98116

99-
<PackageManagers type="run" args="build" />
117+
</Steps>
100118

101-
3. **Deploy your project.**
119+
### If your site uses server rendering
102120

103-
<PackageManagers type="run" args="deploy --assets=dist" />
121+
If your Astro project uses [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/), follow these steps:
104122

105-
</Steps>
123+
<Steps>
124+
1. **Install the Astro Cloudflare adapter.**
125+
<PackageManagers
126+
type="exec"
127+
pkg="astro"
128+
args="add cloudflare"
129+
/>
130+
131+
<Details header="What's happening behind the scenes?">
132+
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).
133+
</Details>
134+
135+
2. **Add a Wrangler configuration file**
136+
137+
In your project root, create a Wrangler configuration file with the following content:
138+
139+
<WranglerConfig>
140+
```json
141+
{
142+
"name": "my-astro-app",
143+
"main": "./dist/_worker.js/index.js",
144+
// Update to today's date
145+
"compatibility_date": "2025-03-25",
146+
"compatibility_flags": ["nodejs_compat"],
147+
"assets": {
148+
"binding": "ASSETS",
149+
"directory": "./dist"
150+
},
151+
"observability": {
152+
"enabled": true
153+
}
154+
}
155+
```
156+
</WranglerConfig>
157+
<Details header="What's this configuration doing?">
158+
The key parts of this config are:
159+
- `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.
160+
- `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.
161+
162+
Read more about [Wrangler configuration options](/workers/wrangler/configuration/) and [asset configuration options](/workers/static-assets/routing/).
163+
</Details>
164+
165+
3. **Build and deploy your project**
166+
167+
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.
168+
169+
<PackageManagers type="exec" pkg="astro" args="build" />
170+
<PackageManagers type="exec" pkg="wrangler@latest" args="deploy" />
171+
172+
</Steps>
173+
174+
## Bindings
175+
176+
:::note
177+
You cannot use bindings if you're using Astro to generate a purely static site.
178+
:::
179+
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`.
180+
181+
## Astro's build configuration
182+
183+
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/).
184+
185+
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.

0 commit comments

Comments
 (0)