1# API Reference
2 
3## ASSETS Binding
4 
5The `ASSETS` binding provides access to static assets via the `Fetcher` interface.
6 
7### Type Definition
8 
9```typescript
10interface Env {
11  ASSETS: Fetcher;
12}
13 
14interface Fetcher {
15  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
16}
17```
18 
19### Method Signatures
20 
21```typescript
22// 1. Forward entire request
23await env.ASSETS.fetch(request);
24 
25// 2. String path (hostname ignored, only path matters)
26await env.ASSETS.fetch("https://any-host/path/to/asset.png");
27 
28// 3. URL object
29await env.ASSETS.fetch(new URL("/index.html", request.url));
30 
31// 4. Constructed Request object
32await env.ASSETS.fetch(new Request(new URL("/logo.png", request.url), {
33  method: "GET",
34  headers: request.headers
35}));
36```
37 
38**Key behaviors:**
39 
40- Host/origin is ignored for string/URL inputs (only path is used)
41- Method must be GET (others return 405)
42- Request headers pass through (affects response)
43- Returns standard `Response` object
44 
45## Request Handling
46 
47### Path Resolution
48 
49```typescript
50// All resolve to same asset:
51env.ASSETS.fetch("https://example.com/logo.png")
52env.ASSETS.fetch("https://ignored.host/logo.png")
53env.ASSETS.fetch("/logo.png")
54```
55 
56Assets are resolved relative to configured `assets.directory`.
57 
58### Headers
59 
60Request headers that affect response:
61 
62| Header | Effect |
63|--------|--------|
64| `Accept-Encoding` | Controls compression (gzip, brotli) |
65| `Range` | Enables partial content (206 responses) |
66| `If-None-Match` | Conditional request via ETag |
67| `If-Modified-Since` | Conditional request via modification date |
68 
69Custom headers pass through but don't affect asset serving.
70 
71### Method Support
72 
73| Method | Supported | Response |
74|--------|-----------|----------|
75| `GET` | ✅ Yes | Asset content |
76| `HEAD` | ✅ Yes | Headers only, no body |
77| `POST`, `PUT`, etc. | ❌ No | 405 Method Not Allowed |
78 
79## Response Behavior
80 
81### Content-Type Inference
82 
83Automatically set based on file extension:
84 
85| Extension | Content-Type |
86|-----------|--------------|
87| `.html` | `text/html; charset=utf-8` |
88| `.css` | `text/css` |
89| `.js` | `application/javascript` |
90| `.json` | `application/json` |
91| `.png` | `image/png` |
92| `.jpg`, `.jpeg` | `image/jpeg` |
93| `.svg` | `image/svg+xml` |
94| `.woff2` | `font/woff2` |
95 
96### Default Headers
97 
98Responses include:
99 
100```
101Content-Type: <inferred>
102ETag: "<hash>"
103Cache-Control: public, max-age=3600
104Content-Encoding: br  (if supported and beneficial)
105```
106 
107**Cache-Control defaults:**
108 
109- 1 hour (`max-age=3600`) for most assets
110- Override via Worker response transformation (see patterns.md:27-35)
111 
112### Compression
113 
114Automatic compression based on `Accept-Encoding`:
115 
116- **Brotli** (`br`): Preferred, best compression
117- **Gzip** (`gzip`): Fallback
118- **None**: If client doesn't support or asset too small
119 
120### ETag Generation
121 
122ETags are content-based hashes:
123 
124```
125ETag: "a3b2c1d4e5f6..."
126```
127 
128Used for conditional requests (`If-None-Match`). Returns `304 Not Modified` if match.
129 
130## Error Responses
131 
132| Status | Condition | Behavior |
133|--------|-----------|----------|
134| `404` | Asset not found | Body depends on `not_found_handling` config |
135| `405` | Non-GET/HEAD method | `{ "error": "Method not allowed" }` |
136| `416` | Invalid Range header | Range not satisfiable |
137 
138### 404 Handling
139 
140Depends on configuration (see configuration.md:45-52):
141 
142```typescript
143// not_found_handling: "single-page-application"
144// Returns /index.html with 200 status
145 
146// not_found_handling: "404-page"
147// Returns /404.html if exists, else 404 response
148 
149// not_found_handling: "none"
150// Returns 404 response
151```
152 
153## Advanced Usage
154 
155### Modifying Responses
156 
157```typescript
158const response = await env.ASSETS.fetch(request);
159 
160// Clone and modify
161return new Response(response.body, {
162  status: response.status,
163  headers: {
164    ...Object.fromEntries(response.headers),
165    'Cache-Control': 'public, max-age=31536000',
166    'X-Custom': 'value'
167  }
168});
169```
170 
171See patterns.md:27-35 for full example.
172 
173### Error Handling
174 
175```typescript
176const response = await env.ASSETS.fetch(request);
177 
178if (!response.ok) {
179  // Asset not found or error
180  return new Response('Custom error page', { status: 404 });
181}
182 
183return response;
184```
185 
186### Conditional Serving
187 
188```typescript
189const url = new URL(request.url);
190 
191// Serve different assets based on conditions
192if (url.pathname === '/') {
193  return env.ASSETS.fetch('/index.html');
194}
195 
196return env.ASSETS.fetch(request);
197```
198 
199See patterns.md for complete patterns.
200