Configuration and binding

Configuring a Worker with assets requires specifying a directory and, optionally, an assets binding, in your Worker’s wrangler.toml file. The assets binding allows you to dynamically fetch assets from within your Worker script (e.g. env.ASSETS.fetch()), similarly to how you might with a make a fetch() call with a Service binding.

Only one collection of static assets can be configured in each Worker.

directory

The folder of static assets to be served. For many frameworks, this is the ./public/, ./dist/, or ./build/ folder.

wrangler.toml

name = "my-worker"
compatibility_date = "2024-09-19"
assets = { directory = "./public/" }

binding

Configuring the optional binding gives you access to the collection of assets from within your Worker script.

wrangler.toml

name = "my-worker"
main = "./src/index.js"
compatibility_date = "2024-09-19"

assets = { directory = "./public/", binding = "ASSETS" }

In the example above, assets would be available through env.ASSETS.

Runtime API Reference

fetch()

Parameters

• request: Request Pass a Request object, URL string, or URL object. Requests made through this method have html_handling and not_found_handling configuration applied to them.

Response

• Promise<Response> Returns a static asset response for the given request.

Example

Your dynamic code can make new, or forward incoming, requests to your project’s static assets using the assets binding.

Take the following example that configures a Worker script to return a response under all requests headed for /api/. Otherwise, the Worker script will pass the incoming request through to the asset binding. In this case, because a Worker script is only invoked when the requested route has not matched any static assets, this will always evaluate not_found_handling behavior.

JavaScript

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api/")) {
      // TODO: Add your custom /api/* logic here.
      return new Response("Ok");
    }
    // Passes the incoming request through to the assets binding.
    // No asset matched this request, so this will evaluate `not_found_handling` behavior.
    return env.ASSETS.fetch(request);
  },
};

TypeScript

interface Env {
  ASSETS: Fetcher;
}

export default {
  async fetch(request, env): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api/")) {
      // TODO: Add your custom /api/* logic here.
      return new Response("Ok");
    }
    // Passes the incoming request through to the assets binding.
    // No asset matched this request, so this will evaluate `not_found_handling` behavior.
    return env.ASSETS.fetch(request);
  },
} satisfies ExportedHandler<Env>;

Routing configuration

For the various static asset routing configuration options, refer to Routing.