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 to return a response under all requests headed for /api/. Otherwise, the Worker will fallback to returning static assets.

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");
    }
    // Otherwise, serve the static assets.
    // Without this, the Worker will error and no assets will be served.
    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");
    }
    // Otherwise, serve the static assets.
    // Without this, the Worker will error and no assets will be served.
    return env.ASSETS.fetch(request);
  },
} satisfies ExportedHandler<Env>;

Routing configuration

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