Skip to content
Cloudflare Docs

Routing

Default behavior

By default, assets are served by attempting to match up the incoming request's pathname to a static asset. The structure and organization of files in your static asset directory, along with any routing configuration, determine the routing paths for your application. When a request invokes a Worker with assets:

  1. If a request is found with a matching path to the current route requested then that asset will always be served.

In this example, request to example.com/blog serves the blog.html file.

A request to example.com/blog serves the /blog.html file.
  1. If there is no Worker script, not_found_handling will be evaluated. By default, a null-body 404-status response will be served.

If a Worker is configured, and there are no assets that match the current route requested, the Worker will be invoked. The Worker can then "fall back" to not_found_handling asset behavior, by passing the incoming request through to the asset binding.

In this example, request to example.com/api doesn't match a static asset so the Worker is invoked.

A request to example.com/blog runs the Worker.

Invoking Worker Script Ahead of Assets

You may wish to run code before assets are served. This is often the case when implementing authentication, logging, personalization, internationalization, or other similar functions. experimental_serve_directly is a configuration option available in wrangler.toml which controls this behavior. When disabled, experimental_serve_directly = false will invoke your Worker's code, regardless of any assets that would have otherwise matched.

Take the following directory structure, wrangler.toml, and user Worker code:

  • wrangler.toml
  • package.json
  • Directorypublic
    • supersecret.txt
  • Directorysrc
    • index.ts
 
name = "my-worker"
compatibility_date = "2024-09-19"
main = "src/index.ts"
assets = { directory = "./public/", binding = "ASSETS", experimental_serve_directly = false }
 
export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === "/supersecret.txt") {
      const auth = request.headers.get("Authorization");
      if (!auth) {
        return new Response("Forbidden", {
          status: 403,
          statusText: "Forbidden",
          headers: {
            "Content-Type": "text/plain",
          },
        });
      }
    }


    return await env.ASSETS.fetch(request);
  },
};

In this example, any request will be routed to our user Worker, due to experimental_serve_directly being disabled. As a result, any request being made /supersecret.txt without an Authorization header will result in a 403.

Routing configuration

There are two options for asset serving that can be configured in wrangler.toml:

1. html_handling

Forcing or dropping trailing slashes on request paths (for example, example.com/page/ vs. example.com/page) is often something that developers wish to control for cosmetic reasons. Additionally, it can impact SEO because search engines often treat URLs with and without trailing slashes as different, separate pages. This distinction can lead to duplicate content issues, indexing problems, and overall confusion about the correct canonical version of a page.

html_handling configuration determines the redirects and rewrites of requests for HTML content. It is used to specify the pattern for canonical URLs, thus where Cloudflare serves HTML content from, and additionally, where Cloudflare redirects non-canonical URLs to.

2. not_found_handling

In the event a request does not match a static asset, and there is no Worker script (or that Worker script calls fetch() on the assets binding), not_found_handling determines how Cloudflare will construct a response.

It can be used to serve single-page applications (SPAs), or to serve custom 404 HTML pages.

If creating a SPA, place an /index.html in your asset directory. When not_found_handling is configured to "single-page-application", this page will be served with a 200 response.

If you have custom 404 HTML pages, and configure not_found_handling to "404-page", Cloudflare will recursively navigate up by pathname segment to serve the nearest 404.html file. For example, you can have a /404.html and /blog/404.html file, and Cloudflare will serve the /blog/404.html file for requests to /blog/not-found and the /404.html file for requests to /foo/bar.

Default configuration

1. html_handling

"auto-trailing-slash" is the default mode if html_handling is not explicitly specified.

Take the following directory structure:

  • file.html
  • Directoryfolder
    • index.html

Based on the incoming requests, the following assets would be served:

Incoming RequestResponseAsset Served
/file200/file.html served
/file.html307 to /file-
/file/307 to /file-
/file/index307 to /file-
/file/index.html307 to /file-
/folder307 to /folder/-
/folder.html307 to /folder/-
/folder/200/folder/index.html
/folder/index307 /folder/-
/folder/index.html307 /folder/-

2. not_found_handling

"none" is the default mode if not_found_handling is not explicitly specified.

For all non-matching requests, Cloudflare will return a null-body 404-status response.

/not-found -> 404
/foo/path/doesnt/exist -> 404

Alternate configuration options

Alternate configuration options are outlined on this page and can be specified in your project's wrangler.toml file. If you're deploying using a framework, these options will be defined by the framework provider.

Example wrangler.toml configuration:

assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }

html_handling = "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"

Take the following directory structure:

  • file.html
  • Directoryfolder
    • index.html

html_handling: "auto-trailing-slash"

Based on the incoming requests, the following assets would be served:

Incoming RequestResponseAsset Served
/file200/file.html
/file.html307 to /file-
/file/307 to /file-
/file/index307 to /file-
/file/index.html307 to /file-
/folder307 to /folder-
/folder.html307 to /folder-
/folder/200/folder/index.html
/folder/index307 /folder-
/folder/index.html307 /folder-

html_handling: "force-trailing-slash"

Based on the incoming requests, the following assets would be served:

Incoming RequestResponseAsset Served
/file307 to /file/-
/file.html307 to /file/-
/file/200/file.html
/file/index307 to /file/-
/file/index.html307 to /file/-
/folder307 to /folder/-
/folder.html307 to /folder/-
/folder/200/folder/index.html
/folder/index307 /folder/-
/folder/index.html307 /folder/-

html_handling: "drop-trailing-slash"

Based on the incoming requests, the following assets would be served:

Incoming RequestResponseAsset Served
/file200/file.html
/file.html307 to /file-
/file/307 to /file-
/file/index307 to /file-
/file/index.html307 to /file-
/folder200/folder/index.html
/folder.html307 to /folder-
/folder/307 to /folder-
/folder/index307 /folder-
/folder/index.html307 /folder-

html_handling: "none"

Based on the incoming requests, the following assets would be served:

Incoming RequestResponseAsset Served
/fileDepends on not_found_handlingDepends on not_found_handling
/file.html200/file.html
/file/Depends on not_found_handlingDepends on not_found_handling
/file/indexDepends on not_found_handlingDepends on not_found_handling
/file/index.htmlDepends on not_found_handlingDepends on not_found_handling
/folderDepends on not_found_handlingDepends on not_found_handling
/folder.htmlDepends on not_found_handlingDepends on not_found_handling
/folder/Depends on not_found_handlingDepends on not_found_handling
/folder/indexDepends on not_found_handlingDepends on not_found_handling
/folder/index.html200/folder/index.html

not_found_handling = "404-page" | "single-page-application" | "none"

Take the following directory structure:

  • 404.html
  • index.html
  • Directoryfolder
    • 404.html

not_found_handling: "none"

/not-found -> 404
/folder/doesnt/exist -> 404

not_found_handling: "404-page"

/not-found -> 404 /404.html
/folder/doesnt/exist -> 404 /folder/404.html

not_found_handling: "single-page-application"

/not-found -> 200 /index.html
/folder/doesnt/exist -> 200 /index.html

Serving assets from a custom path

Like with any other Worker, you can configure a Worker with assets to run on a path of your domain. Assets defined for a Worker must be nested in a directory structure that mirrors the desired path.

For example, to serve assets from example.com/blog/*, create a blog directory in your asset directory.

  • Directorydist
    • Directoryblog
      • index.html
      • Directoryposts
        • post1.html
        • post2.html

With a Wrangler configuration file like so:

name = "assets-on-a-path-example"
main = "src/index.js"
route = "example.com/blog/*"


[assets]
directory = "dist"

In this example, requests to example.com/blog/ will serve the index.html file, and requests to example.com/blog/posts/post1 will serve the post1.html file.

If you have a file outside the configured path, it will not be served. For example, if you have a home.html file in the root of your asset directory, it will not be served when requesting example.com/blog/home. However, if needed, these files can still be manually fetched over the binding.

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings