Serving Cloudflare Workers Static Assets from a URL Prefix

Cloudflare Workers static asset handling has been extended to support a configurable URL prefix. By setting assets.base_path (Wrangler) or worker.assets.basePath (cloudflare.config.ts) you can serve files from a path such as /blog while keeping the on‑disk layout unchanged. The change is available starting with Wrangler 4.148.0 and cf 1.0.0‑beta.13.

New Base‑Path Option

The addition is a single configuration field that tells the Workers runtime to prepend a static segment to every asset request. The underlying file system remains the same, so build pipelines do not need to copy or rename directories to match the public URL structure.

Configuring the Prefix

Both the JSON‑style and TOML configuration formats accept the new key. Below are minimal examples that map the dist folder to /blog:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "assets": {
    "directory": "./dist",
    "base_path": "/blog"
  }
}

[assets]
 directory = "./dist"
 base_path = "/blog"

When using cloudflare.config.ts, the same effect is achieved with:

import { defineConfig } from "cf/config";

export default defineConfig({
  worker: {
    assets: {
      basePath: "/blog",
      directory: "./dist"
    }
  }
});

Operational Implications

• Routing simplicity: Edge functions that already match /blog/* can now rely on the static asset layer without additional rewrite rules.
• Cache keys: The prefix becomes part of the cache key, so existing CDN‑level caching policies continue to work as expected.
• Version lock‑in: The feature only works with the specified Wrangler and cf releases; older tooling will ignore the field and serve assets from the root.
• Testing: Verify that URLs like /blog/index.html resolve correctly and that 404s are not introduced by mismatched prefixes.

Security Considerations

Introducing a path prefix does not change the underlying access model, but it does expand the public surface area of the worker. Practitioners should ensure that any path‑based validation or rate‑limiting logic accounts for the new prefix. Additionally, because the prefix is part of the request URL, logging and monitoring should be updated to capture the full path for accurate incident analysis.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

Adopt the new base_path setting in your next deployment to avoid restructuring static assets for custom URLs. Confirm you are on Wrangler 4.148.0+ (or cf 1.0.0‑beta.13+), update the configuration as shown, and run a quick smoke test against the prefixed endpoint. Monitor cache hit ratios and error logs for any unexpected behavior, and adjust any edge‑routing rules that previously rewrote URLs to accommodate the new static‑asset prefix.