Serve Cloudflare Workers static assets from a custom URL prefix

Cloudflare Workers can now expose static files under an arbitrary path prefix without reorganising the asset directory on disk. By adding a basePath (or worker.assets.basePath) entry to the project configuration, the same root‑level files are served as if they lived under the chosen URL segment, for example /blog/. The change is limited to configuration; the underlying runtime and edge delivery remain unchanged.

What Changed

Earlier, serving assets from /blog/ required a physical blog folder inside the asset bundle. The new approach decouples the URL structure from the file layout. Two configuration styles are supported:

• In a cloudflare.config.ts file, set worker.assets.basePath to the desired prefix.
• In a wrangler.toml (or wrangler.jsonc) file, set assets.base_path to the same value.

The feature is available starting with Wrangler 4.148.0 and cf 1.0.0‑beta.13.

import { defineConfig } from "cf/config";
export default defineConfig({
  worker: {
    name: "blog",
    compatibilityDate: "2026-11-12",
    assets: {
      basePath: "/blog",
    },
  },
});

Why It Matters to Practitioners

For AI, cloud, DevOps, and security engineers the benefit is practical rather than promotional:

• Build simplicity: No need to duplicate or relocate files to match a URL hierarchy, keeping the source tree clean.
• Pipeline stability: CI/CD steps that package assets can remain unchanged; only the config file is updated.
• Consistent routing: The edge runtime automatically maps the prefix, reducing the chance of mismatched routes between code and static content.
• Version alignment: The change is gated behind recent CLI releases, encouraging teams to stay on supported toolchains.

Architectural and Operational Implications

Introducing a base path does not alter the underlying Workers architecture, but it does affect how assets are resolved at the edge:

• The edge server prepends the configured basePath to every static request, so any custom routing logic must account for the prefix.
• Cache keys now include the prefix, which may affect cache hit ratios if the same assets are served under multiple prefixes.
• Upgrade paths: projects must adopt Wrangler ≥ 4.148.0 or cf ≥ 1.0.0‑beta.13. Teams should verify that their CI agents and local dev environments meet these minimum versions.
• Configuration drift: because the asset location is now decoupled from the file system, divergent config files across environments can cause unexpected 404s. Centralising the config in version control mitigates this risk.

Security Considerations

The feature itself does not introduce new authentication or authorization mechanisms, but it does change the exposure surface of static content:

• Path‑based access control must be reviewed. If a prefix is used to separate public and internal assets, ensure that any edge‑level firewall or Workers logic still enforces the intended restrictions.
• Because the same physical files can be served under multiple prefixes, accidental duplication of sensitive files under a public prefix becomes possible if the config is mis‑typed.
• Audit logs will now record requests with the configured prefix, which can aid in monitoring but also requires updated alerting rules.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

Adopt the new basePath setting in your next deployment to eliminate directory‑level workarounds. Verify that your build scripts, CI pipelines, and any custom routing code respect the chosen prefix. Upgrade to the required CLI versions, run a quick smoke test against the edge URL, and confirm that caching and security policies still behave as expected. Monitoring for 404s or unexpected cache misses after the change will surface any misconfiguration early.