Add assets.html_handling mode to *preserve .html filenames* while still serving /folder/ → /folder/index.html

[kensukesaito]

Background

Today, assets.html_handling supports four modes: "auto-trailing-slash" (default), "force-trailing-slash", "drop-trailing-slash", and "none". In the default mode, a request to /file.html redirects to /file (the .html extension is dropped), while /folder/ serves /folder/index.html. When "html_handling": "none", /file.html is served as-is but /folder/ no longer maps to /folder/index.html (typically a 404 unless otherwise configured). (Cloudflare Docs)

Problem

There is no mode that reproduces the “traditional” static web server behavior:

• Keep .html in the canonical URL (no forced extensionless redirect).
• Still treat /folder/ as the canonical directory URL that serves /folder/index.html.

"auto-trailing-slash" removes .html, while "none" loses directory index behavior. (Cloudflare Docs)

Proposal

Add a new assets.html_handling value, e.g. "preserve-extension" (alternatives: "traditional", "classic", "keep-extension"), with rules:

• Exact .html match: Serve without redirect.
  /file.html → 200 /dist/file.html
• Extensionless request that matches a .html file: Redirect to the .html filename (to avoid duplicate content).
  /file → 307 /file.html
• Directory paths: Canonicalize to a trailing slash and serve the index.
  /folder → 307 /folder/ → 200 /dist/folder/index.html

This mirrors current behavior for directory indexes while preserving .html as canonical—essentially the inverse of the current extension-dropping default. Existing assets.not_found_handling semantics remain unchanged. (Cloudflare Docs)

Prior art / comparison

Major cloud providers’ static site hosting follows the traditional model by default:

• Amazon S3 Static Website Hosting: You configure an index document that S3 returns for the root and any subfolder, e.g., /folder/ → /folder/index.html. S3 does not drop .html extensions automatically. (AWS Documentation)
• Google Cloud Storage: Setting MainPageSuffix serves the matching index for a requested prefix (directory), e.g., /folder/ resolves to /folder/index.html, and .html filenames are served as named. (Google Cloud)
• Azure Blob Storage (Static website): You specify an Index document name that is served at the root and in subfolders; there’s no automatic .html stripping. (Microsoft Learn)

Given this ecosystem baseline, Cloudflare Workers Static Assets would benefit from supporting the same traditional behavior out of the box. In fact, it may be more intuitive if this traditional behavior were the default, and the current "auto-trailing-slash" (extension-dropping) behavior were opt-in via configuration. (Cloudflare Docs)

Why this helps

• Preserves long-standing URLs with .html extensions without forced redirects.
• Maintains expected directory index behavior for /folder/.
• Avoids pushing users to run_worker_first and custom routing just to emulate classical semantics.
• Aligns Workers with S3/GCS/Azure static hosting defaults, smoothing migrations. (AWS Documentation)

Thanks for considering this!

[dario-piotrowicz]

Hi @kensukesaito, thank you very much for the issue 🙂

I have raised this with the team and we're generally open to this idea, the team is however quite busy and we unsure wether there is a significant demand for this.

So for the time being we'll keep an eye on this issue, if more people comment / like this issue and we do get a signal that there is enough demand for this feature we'll happily implement it 😄

[kensukesaito]

Hi @dario-piotrowicz ,

Thanks for the quick follow-up and for raising this internally — appreciated!

Just to add a bit more signal on why this would help:

• Ecosystem parity / easier migrations. The “traditional” model (keep .html when requested, and map /folder/ → /folder/index.html) is how the big static hosts behave out of the box:

  • Amazon S3 static website hosting serves the configured index document at the root and any subfolder; it doesn’t auto-strip .html. (AWS Documentation)
  • Google Cloud Storage uses a main page suffix so directory requests resolve to index.html, while .html files are served as named. (Google Cloud)
  • Azure Blob Storage (static website) similarly serves an Index document name for root and subfolders. (Microsoft Learn)
    Today, Workers Static Assets defaults to html_handling = "auto-trailing-slash" (drops .html), which makes 1:1 migrations surprisingly lossy unless users add a Worker or rewrite URLs. (Cloudflare Docs)

• URL stability for docs/legacy sites. Lots of documentation sets and older sites intentionally canonize .html URLs. Auto-dropping the extension forces redirect layers or link updates that wouldn’t be needed if there were a “preserve extension + directory index” mode. (Current docs show no mode that preserves .html and keeps /folder/ → /folder/index.html.) (Cloudflare Docs)

Concretely, the proposed mode (e.g., html_handling = "preserve-extension") would:

• serve /file.html as-is,
• redirect /file → /file.html when a match exists,
• and map /folder/ → /folder/index.html with trailing-slash canonicalization—mirroring S3/GCS/Azure defaults. (Cloudflare Docs)

Totally understand the team is busy. Even if this isn’t prioritized immediately, I hope the above shows there’s practical demand from folks migrating standard static sites to Workers. If others land here and share this need, please add a 👍/use-case so the team can gauge interest.

[rauschma]

I have the same need: I’d like to migrate an existing site to Cloudflare and the redirections change existing URLs which is not good.

I solved it as follows via a Worker, but a simpler approach would be nice to have: https://github.com/rauschma/cloudflare-worker-assets-demo