You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -7,63 +7,184 @@ description: Create an Astro application and deploy it to Cloudflare Workers wit
7
7
8
8
import {
9
9
Badge,
10
+
Details,
11
+
Steps,
12
+
WranglerConfig,
10
13
Description,
11
14
InlineBadge,
12
15
Render,
16
+
TabItem,
17
+
Tabs,
13
18
PackageManagers,
14
19
} from"~/components";
15
20
16
-
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/)).
17
-
18
-
## 1. Set up a new project
19
-
20
-
Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Astro's official setup tool, and provide the option to deploy instantly.
21
-
22
-
To use `create-cloudflare` to create a new Astro project with Workers Assets, run the following command:
21
+
**Start from CLI**: Scaffold an Astro project on Workers, and pick your template.
23
22
24
23
<PackageManagers
25
24
type="create"
26
25
pkg="cloudflare@latest my-astro-app"
27
-
args={"--framework=astro --platform=workers"}
26
+
args="--framework=astro --platform=workers"
28
27
/>
29
28
30
-
<Render
31
-
file="c3-post-run-steps"
32
-
product="workers"
33
-
params={{
34
-
category: "web-framework",
35
-
framework: "Astro",
36
-
}}
37
-
/>
29
+
---
38
30
39
-
After setting up your project, change your directory by running the following command:
31
+
**Or just deploy**: Create a static blog with Astro and deploy it on Cloudflare Workers, with CI/CD and previews all set up for you.
40
32
41
-
```sh
42
-
cd my-astro-app
43
-
```
33
+
[](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/staging/astro-blog-starter-template)
44
34
45
-
## 2. Develop locally
35
+
## What is Astro?
46
36
47
-
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.
37
+
[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).
48
38
49
-
<PackageManagerstype="run"args={"dev"} />
39
+
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.
50
40
51
-
## 3. Deploy your Project
41
+
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/).
52
42
53
-
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/).
43
+
## Deploy a new Astro project on Workers
54
44
55
-
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.
45
+
<Steps>
46
+
1.**Create a new project with the create-cloudflare CLI (C3).**
<Detailsheader="What's happening behind the scenes?">
54
+
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.
58
55
59
-
---
56
+
</Details>
57
+
58
+
2.**Develop locally.**
59
+
60
+
After creating your project, run the following command in your project directory to start a local development server.
61
+
62
+
<PackageManagerstype="run"args="dev" />
63
+
64
+
3.**Deploy your project.**
65
+
66
+
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.
67
+
68
+
<PackageManagerstype="run"args="deploy" />
69
+
70
+
</Steps>
71
+
72
+
## Deploy an existing Astro project on Workers
73
+
74
+
### If you have a static site
75
+
76
+
If your Astro project is entirely pre-rendered, follow these steps:
77
+
78
+
<Steps>
79
+
1.**Add a Wrangler configuration file**
80
+
81
+
In your project root, create a Wrangler configuration file with the following content:
82
+
83
+
<WranglerConfig>
84
+
85
+
```json
86
+
{
87
+
"name": "my-astro-app",
88
+
// Update to today's date
89
+
"compatibility_date": "2025-03-25",
90
+
"assets": {
91
+
"directory": "./dist"
92
+
}
93
+
}
94
+
```
95
+
96
+
</WranglerConfig>
97
+
<Detailsheader="What's this configuration doing?">
98
+
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.
99
+
Read about other [asset configuration options](/workers/static-assets/routing/).
100
+
101
+
Also note how there's no `main` field in this config - this is because you're only serving static assets, so no Worker code is needed for on demand rendering/SSR.
102
+
</Details>
103
+
104
+
2.**Build and deploy your project**
105
+
106
+
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.
If your Astro project uses [on demand rendering (also known as SSR)](https://docs.astro.build/en/guides/on-demand-rendering/), follow these steps:
116
+
117
+
<Steps>
118
+
1.**Install the Astro Cloudflare adapter**
119
+
<PackageManagers
120
+
type="exec"
121
+
pkg="astro"
122
+
args="add cloudflare"
123
+
/>
124
+
125
+
<Detailsheader="What's happening behind the scenes?">
126
+
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 on demand rendering/SSR, 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).
127
+
</Details>
128
+
129
+
2.**Add a `.assetsignore` file**
130
+
Create a `.assetsignore` file in your `public/` folder, and add the following lines to it:
131
+
132
+
```title=".assetsignore"
133
+
_worker.js
134
+
_routes.json
135
+
```
136
+
137
+
3.**Add a Wrangler configuration file**
138
+
139
+
In your project root, create a Wrangler configuration file with the following content:
140
+
141
+
<WranglerConfig>
142
+
```json
143
+
{
144
+
"name": "my-astro-app",
145
+
"main": "./dist/_worker.js/index.js",
146
+
// Update to today's date
147
+
"compatibility_date": "2025-03-25",
148
+
"compatibility_flags": ["nodejs_compat"],
149
+
"assets": {
150
+
"binding": "ASSETS",
151
+
"directory": "./dist"
152
+
},
153
+
"observability": {
154
+
"enabled": true
155
+
}
156
+
}
157
+
```
158
+
</WranglerConfig>
159
+
<Detailsheader="What's this configuration doing?">
160
+
The key parts of this config are:
161
+
- `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.
162
+
- `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.
163
+
164
+
Read more about [Wrangler configuration options](/workers/wrangler/configuration/) and [asset configuration options](/workers/static-assets/routing/).
165
+
</Details>
166
+
167
+
4.**Build and deploy your project**
168
+
169
+
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.
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`.
178
+
:::note
179
+
You cannot use bindings if you're using Astro to generate a purely static site.
180
+
:::
181
+
182
+
With bindings, your Astro application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more. Refer to the [bindings overview](/workers/runtime-apis/bindings/) for more information on what's available and how to configure them.
183
+
184
+
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`.
64
185
65
-
## Static assets
186
+
## Astro's build configuration
66
187
67
-
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.
188
+
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 on demand rendering/SSR, 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/).
68
189
69
-
<Renderfile="workers-assets-routing-summary" />
190
+
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