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
Create fast, scalable front-end applications deployed to Cloudflare Workers.
28
-
</Description>
30
+
Cloudflare Workers simplify hosting and serving static like (such as HTML, CSS, images, and other resources) by combining a globally distributed CDN with lightweight, serverless backend logic.
31
+
32
+
With Workers, you can:
33
+
34
+
-**Host static sites** or **Single Page Applications (SPAs)** across Cloudflare's network.
35
+
36
+
-**Add backend logic** (such as APIs or custom middleware) alongside your assets without needing a dedicated server.
37
+
38
+
- Serve content to users with **low latency** using **built-in caching** for faster load times for users worldwide.
39
+
40
+
-**Build full-stack applications** using Cloudflare's storage solutions, such as [R2](/r2/) for object storage, [KV](/kv/) for distributed key-value storage, [D1](/d1/) for relational databases, and [Durable Objects](/durable-objects/) for stateful, consistent storage and coordination. You can also connect to existing databases using [Hyperdrive](/hyperdrive/)
41
+
42
+
---
43
+
44
+
## Basic Workflow
45
+
46
+
---
47
+
48
+
From a high-level, here's how you can get started with deploying a simple static site on Workers:
49
+
50
+
<Steps>
51
+
1. Build your static assets.
52
+
```sh
53
+
npm run build
54
+
```
55
+
<Detailsheader="Don't have an existing project?">
56
+
You can quickly scaffold a project using [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project):
57
+
```sh
58
+
npm create vite@latest
59
+
```
60
+
And follow the prompts! For first-timers, just select `vanilla` as your template.
61
+
</Details>
62
+
2. Add and configure a Wrangler configuration file (`wrangler.toml` or `wrangler.json`)
63
+
64
+
<WranglerConfig>
65
+
```toml
66
+
name = "my-static-site"
67
+
compatibility_date = "2025-01-01"
68
+
[assets]
69
+
directory = "./dist"
70
+
```
71
+
</WranglerConfig>
72
+
73
+
In this configuration file, you define the **directory** where Cloudflare can find your built assets that need to be uploaded. To do this, we've added an `[assets]` block, and specified the `directory` as `dist/`.
74
+
75
+
3. Deploy with Wrangler
76
+
77
+
```sh
78
+
npx wrangler deploy
79
+
```
80
+
81
+
And let Cloudflare Workers handle asset uploading, routing, and caching automatically!
82
+
83
+
</Steps>
29
84
30
85
---
31
86
32
-
## What you can build
87
+
## How it works
88
+
89
+
When you deploy your app with Wrangler, it deploys both your Worker script and your static assets in a single operation. This deployment operates as a tightly integrated "unit" running across Cloudflare's network, combining static file hosting, custom logic, and global caching.
90
+
91
+
Within this deployment, the Worker has two primary responsibilies:
92
+
93
+
1.**Asset handling**
94
+
2.**Running custom logic**
95
+
96
+
### Asset handling
97
+
98
+
Static asset hosting on Workers allows you to serve files such as HTML, JavaScript, CSS, images, and other resources directly from Cloudflare's global network. This setup eliminates the need for a traditional web server, simplifying deployment and optimizing performance.
99
+
100
+
The **assets directory** specified in your Wrangler configuration file is central to this design. During deployment, Wrangler automatically uploads the files from this directory to Cloudflare’s infrastructure. Once deployed, requests for these assets are routed efficiently to locations closest to your users.
101
+
102
+
This approach ensures that static files like `index.html`, JavaScript bundles, stylesheets, and images are served with minimal latency. Workers efficiently handle file resolution, meaning they serve files as-is from the defined directory, or return a fallback response (such as an error or default page) when a requested file is not found.
103
+
104
+
<Asidetype="tip">
105
+
You can control how assets are served, how unmatched routes are handled, as
106
+
well as override routing behavior in your Wrangler configuration file.
107
+
108
+
For example, if you have a Single Page Application and want to fallback to
109
+
`index.html` for unmatched routes, you can define this in your [Wrangler configuration](/workers/static-assets/routing/#alternate-configuration-options):
110
+
111
+
<WranglerConfig>
112
+
```toml
113
+
name = "my-static-site"
114
+
compatibility_date = "2025-01-01"
115
+
[assets]
116
+
directory = "./dist"
117
+
not_found_handling = "single-page-application"
118
+
119
+
```
120
+
</WranglerConfig>
121
+
122
+
</Aside>
123
+
124
+
### Running custom logic
125
+
126
+
One of the defining features of Cloudflare Workers is the ability to execute custom backend logic alongside your static assets. This logic can be used for handling requests, modifying responses, or implementing custom functionality for your application.
127
+
128
+
For example, you can implement the following directly in your Worker:
129
+
130
+
-**Dynamic routing:** Inspect incoming requests and route them based on their paths or headers. For example, you can route requests to `/api` to custom API logic, while static files are automatically served from your specified directory.
131
+
132
+
-**API endpoints:** Define endpoints to handle user requests, fetch data from external APIs, or interact with databases.
133
+
134
+
-**Response modifications:** Modify responses dynamically, such as adding headers, compressing payloads, or injecting data into static content.
135
+
136
+
-**Stateful logic:** For scenarios requiring consistent state across requests, you can use [Durable Objects](/durable-objects/). Durable objects allow you to maintain state for use-cases such as real-time collaboration, session storage, global counters, and more.
137
+
138
+
<Asidetype="tip">
139
+
You can change the default routing behavior (which prioritizes serving assets ahead of running Worker code) so that your [Worker code runs before an asset is served](/workers/static-assets/routing/#invoking-worker-script-ahead-of-assets/).
140
+
141
+
For example, if you want to protect an asset behind authentication, you can override the routing behavior in your Wrangler configuration file:
33
142
34
-
### Static Websites
143
+
<WranglerConfig>
144
+
```toml
145
+
name = "my-static-site"
146
+
compatibility_date = "2025-01-01"
147
+
[assets]
148
+
directory = "./dist"
149
+
binding = "ASSETS"
150
+
experimental_serve_directly = false
151
+
```
152
+
</WranglerConfig>
35
153
36
-
Deploy static sites like blogs, portfolios, or documentation pages. Serve HTML, CSS, JavaScript, and media files directly from Cloudflare's network for low-latency access worldwide.
Cloudflare provides automatic caching for static assets across its network, ensuring fast delivery to users worldwide. When a static asset is requested, it is automatically cached for future requests.
43
159
44
-
Build dynamic and interactive server-side rendered (SSR) applications on Cloudflare Workers.
160
+
#### Cache behavior
45
161
46
-
You can combine asset hosting with Cloudflare's data and storage products such as [Workers KV](/kv/), [Durable Objects](/durable-objects/), and [R2 Storage](/r2/) to build full-stack applications that serve both front-end and back-end logic in a single Worker.
162
+
-**First Request:** When an asset is requested for the first time, it is fetched from storage and cached at the nearest location.
-**Subsequent Requests:** Future requests for the same asset are served directly from the cache, significantly reducing latency.
51
165
52
-
###Supported frameworks
166
+
## Supported frameworks
53
167
54
168
The following Frameworks are currently supported on Cloudflare Workers:
55
169
@@ -61,19 +175,19 @@ Static Assets for Workers is currently in open beta. If you're looking for a fra
61
175
62
176
:::
63
177
64
-
###Pricing
178
+
## Pricing
65
179
66
180
Requests to a project with static assets can either return static assets or invoke the Worker script, depending on if the request [matches a static asset or not](/workers/static-assets/routing/).
67
181
68
182
**Requests to static assets are free and unlimited**. Requests to the Worker script (e.g. in the case of SSR content) are billed according to Workers pricing. Refer to [pricing](/workers/platform/pricing/#example-2) for an example.
69
183
70
184
There is no additional cost for storing Assets.
71
185
72
-
###Troubleshooting
186
+
## Troubleshooting
73
187
74
188
-`assets.bucket is a required field` — if you see this error, you need to update Wrangler to at least `3.78.10` or later. `bucket` is not a required field.
75
189
76
-
###Limitations
190
+
## Limitations
77
191
78
192
The following limitations apply for Workers with static assets:
Copy file name to clipboardExpand all lines: src/content/docs/workers/static-assets/routing.mdx
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
pcx_content_type: concept
3
3
title: Routing
4
4
sidebar:
5
-
order: 7
5
+
order: 9
6
6
head: []
7
7
description: How Workers assets' routing and its configuration works.
8
8
---
@@ -322,3 +322,4 @@ In this example, requests to `example.com/blog/` will serve the `index.html` fil
322
322
323
323
If you have a file outside the configured path, it will not be served. For example, if you have a `home.html` file in the root of your asset directory, it will not be served when requesting `example.com/blog/home`.
324
324
However, if needed, these files can still be manually fetched over [the binding](/workers/static-assets/binding/#binding).
0 commit comments