dotfiles/.agents/skills/cloudflare-deploy/references/static-assets/api.md

API Reference

ASSETS Binding

The ASSETS binding provides access to static assets via the Fetcher interface.

Type Definition

interface Env {
  ASSETS: Fetcher;
}

interface Fetcher {
  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
}

Method Signatures

// 1. Forward entire request
await env.ASSETS.fetch(request);

// 2. String path (hostname ignored, only path matters)
await env.ASSETS.fetch("https://any-host/path/to/asset.png");

// 3. URL object
await env.ASSETS.fetch(new URL("/index.html", request.url));

// 4. Constructed Request object
await env.ASSETS.fetch(new Request(new URL("/logo.png", request.url), {
  method: "GET",
  headers: request.headers
}));

Key behaviors:

• Host/origin is ignored for string/URL inputs (only path is used)
• Method must be GET (others return 405)
• Request headers pass through (affects response)
• Returns standard Response object

Request Handling

Path Resolution

// All resolve to same asset:
env.ASSETS.fetch("https://example.com/logo.png")
env.ASSETS.fetch("https://ignored.host/logo.png")
env.ASSETS.fetch("/logo.png")

Assets are resolved relative to configured assets.directory.

Headers

Request headers that affect response:

Header	Effect
Accept-Encoding	Controls compression (gzip, brotli)
Range	Enables partial content (206 responses)
If-None-Match	Conditional request via ETag
If-Modified-Since	Conditional request via modification date

Custom headers pass through but don't affect asset serving.

Method Support

Method	Supported	Response
GET	✅ Yes	Asset content
HEAD	✅ Yes	Headers only, no body
POST, PUT, etc.	❌ No	405 Method Not Allowed

Response Behavior

Content-Type Inference

Automatically set based on file extension:

Extension	Content-Type
.html	text/html; charset=utf-8
.css	text/css
.js	application/javascript
.json	application/json
.png	image/png
.jpg, .jpeg	image/jpeg
.svg	image/svg+xml
.woff2	font/woff2

Default Headers

Responses include:

Content-Type: <inferred>
ETag: "<hash>"
Cache-Control: public, max-age=3600
Content-Encoding: br  (if supported and beneficial)

Cache-Control defaults:

• 1 hour (max-age=3600) for most assets
• Override via Worker response transformation (see patterns.md:27-35)

Compression

Automatic compression based on Accept-Encoding:

• Brotli (br): Preferred, best compression
• Gzip (gzip): Fallback
• None: If client doesn't support or asset too small

ETag Generation

ETags are content-based hashes:

ETag: "a3b2c1d4e5f6..."

Used for conditional requests (If-None-Match). Returns 304 Not Modified if match.

Error Responses

Status	Condition	Behavior
404	Asset not found	Body depends on not_found_handling config
405	Non-GET/HEAD method	{ "error": "Method not allowed" }
416	Invalid Range header	Range not satisfiable

404 Handling

Depends on configuration (see configuration.md:45-52):

// not_found_handling: "single-page-application"
// Returns /index.html with 200 status

// not_found_handling: "404-page"
// Returns /404.html if exists, else 404 response

// not_found_handling: "none"
// Returns 404 response

Advanced Usage

Modifying Responses

const response = await env.ASSETS.fetch(request);

// Clone and modify
return new Response(response.body, {
  status: response.status,
  headers: {
    ...Object.fromEntries(response.headers),
    'Cache-Control': 'public, max-age=31536000',
    'X-Custom': 'value'
  }
});

See patterns.md:27-35 for full example.

Error Handling

const response = await env.ASSETS.fetch(request);

if (!response.ok) {
  // Asset not found or error
  return new Response('Custom error page', { status: 404 });
}

return response;

Conditional Serving

const url = new URL(request.url);

// Serve different assets based on conditions
if (url.pathname === '/') {
  return env.ASSETS.fetch('/index.html');
}

return env.ASSETS.fetch(request);

See patterns.md for complete patterns.