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.

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.

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
TypeScript

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);
  },
};

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.

Was this helpful?

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings