Configuration and Bindings

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
wrangler.json

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

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

Ignoring assets

Sometime there are files in the asset directory that should not be uploaded.

In this case, create a .assetsignore file in the root of the assets directory. This file takes the same format as .gitignore.

Wrangler will not upload asset files that match lines in this file.

Example

You are migrating from a Pages project where the assets directory is dist. You do not want to upload the server-side Worker code nor Pages configuration files as public client-side assets. Add the following .assetsignore file:

_worker.js
_redirects
_headers

Now Wrangler will not upload these files as client-side assets when deploying the Worker.

`experimental_serve_directly`

Controls whether assets will be served first on a matching request. experimental_serve_directly = true (default) will serve any static asset matching a request, while experimental_serve_directly = false will unconditionally invoke your Worker script.

wrangler.toml
wrangler.json

name = "my-worker"
compatibility_date = "2024-09-19"
main = "src/index.ts"
 # The following configuration unconditionally invokes the Worker script at
 # `src/index.ts`, which can programatically fetch assets via the ASSETS binding
assets = { directory = "./public/", binding = "ASSETS", experimental_serve_directly = false }

{
  "name": "my-worker",
  "compatibility_date": "2024-09-19",
  "main": "src/index.ts",
  "assets": {
    "directory": "./public/",
    "binding": "ASSETS",
    "experimental_serve_directly": false
  }
}

`binding`

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

wrangler.toml
wrangler.json

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

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

{
  "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.

Smart Placement

Smart Placement can be used to place a Worker's code close to your back-end infrastructure. Smart Placement will only have an effect if you specified a main, pointing to your Worker code.

Smart Placement with Worker Code First

If you desire to run your Worker code ahead of assets by setting experimental_serve_directly=false, all requests must first travel to your Smart-Placed Worker. As a result, you may experience increased latency for asset requests.

Use Smart Placement with experimental_serve_directly=false when you need to integrate with other backend services, authenticate requests before serving any assets, or if your want to make modifications to your assets before serving them.

If you want some assets served as quickly as possible to the user, but others to be served behind a smart-placed Worker, considering splitting your app into multiple Workers and using service bindings to connect them.

Smart Placement with Assets First

Enabling Smart Placement with experimental_serve_directly=true lets you serve assets from as close as possible to your users, but moves your Worker logic to run most efficiently (such as near a database).

Use Smart Placement with experimental_serve_directly=true when prioritizing fast asset delivery.

This will not impact the default routing behavior.

Was this helpful?

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings