Clean URLs and Trailing Slashes on S3

Every static site generator writes pages as directories: guides/deploying/index.html, served at /guides/deploying/. Managed static hosts resolve that mapping automatically. S3 does not. It is an object store, and its REST endpoint looks for an object whose key is literally guides/deploying/ — which does not exist — and returns an XML AccessDenied or NoSuchKey error. CloudFront's "default root object" setting only helps for /. The result is a deploy where the homepage works and every other internal link is broken.

This guide fixes that with a small CloudFront Function that rewrites directory URLs to their index.html keys and enforces one canonical trailing-slash form, then proves it with tests. It is part of Self-Hosting Static Sites on S3, Nginx and Caddy and follows on from Deploying a Static Site to S3 and CloudFront.

Prerequisites

• A private S3 bucket behind CloudFront with Origin Access Control.
• A generator configured for directory-style output and a known trailing-slash policy (Astro trailingSlash: 'always', Hugo's default, Eleventy's default permalinks).
• Permission to create CloudFront Functions and associate them with the distribution.

Why the Website Endpoint Is Not the Answer

S3's static website hosting feature does resolve index documents in subdirectories, and older tutorials use it for exactly this reason. But the website endpoint serves plain HTTP only, requires the bucket to be public, and cannot be restricted to CloudFront with Origin Access Control. Anyone can bypass the CDN and its security headers by requesting the bucket's website URL directly. The REST endpoint plus a small function gives the same URL behaviour with a private bucket.

There is a second, subtler cost to the website endpoint: it answers errors itself, with S3's own HTML error document, and it does not support HTTPS between CloudFront and the origin. Security audits of self-hosted sites routinely flag both. Teams sometimes keep the website endpoint for its redirect rules feature, but S3 routing rules are limited to fifty entries and evaluated in order, which makes them unsuitable for a real migration's redirect list. Everything they do is better done in the same viewer function, as the next guide shows.

Step 1: Pick the Canonical Form

Decide once whether URLs end in a slash, and make the generator, internal links, sitemap and canonical tags all agree. For directory-style output, trailing slashes are the natural choice:

Step 2: Write the CloudFront Function

CloudFront Functions run a restricted JavaScript runtime at every edge location, in under a millisecond, on viewer requests:

// cloudfront-function: docs-clean-urls (runtime cloudfront-js-2.0)
function handler(event) {
  var req = event.request;
  var uri = req.uri;
  var qs = Object.keys(req.querystring).length
    ? '?' + Object.entries(req.querystring).map(function (e) { return e[0] + '=' + e[1].value; }).join('&')
    : '';

  if (uri.endsWith('/index.html')) {
    return redirect(uri.slice(0, -'index.html'.length) + qs);
  }
  var last = uri.substring(uri.lastIndexOf('/') + 1);
  if (last.indexOf('.') !== -1) {
    return req;                                  // asset or file with extension
  }
  if (!uri.endsWith('/')) {
    return redirect(uri + '/' + qs);
  }
  req.uri = uri + 'index.html';
  return req;
}

function redirect(location) {
  return {
    statusCode: 301,
    statusDescription: 'Moved Permanently',
    headers: {
      location: { value: location },
      'cache-control': { value: 'public, max-age=3600' },
    },
  };
}

Associate it with the distribution's default cache behaviour as a viewer request function. Because it runs before the cache lookup, /guides/deploying/ and the rewritten key share one cache entry. Keep redirect responses cacheable for an hour rather than a year: a 301 cached by browsers for a year is very hard to undo if the canonical policy ever changes.

Step 3: Handle the Root and 404s

The root path / ends with a slash, so the function rewrites it to /index.html — no default root object needed, though setting it does no harm. For missing pages, a private bucket returns 403 (it does not reveal whether a key exists). Configure CloudFront custom error responses to map both 403 and 404 from the origin to /404.html with status code 404, and cache the error for a short time — 60 seconds — so a page added in the next deploy does not stay missing at the edge.

Other Generators' Output Styles

Not every site uses directory output. VitePress with cleanUrls: true and Hugo with uglyURLs = true write guides/deploying.html and link to /guides/deploying with no slash and no extension. For that style, invert the policy: canonical URLs have no trailing slash, the function appends .html to extensionless paths, and requests with a trailing slash or an explicit .html redirect to the bare form. The structure of the function is identical; only the three branches change. Whatever the style, derive the rule from what the generator writes, not from preference — a policy that fights the generator's links produces a redirect on every internal navigation.

Step 4: Test Every Form

A short script against the live distribution proves each row of the table:

B=https://docs.example.com
t() { printf '%-42s ' "$1"; curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' "$B$1"; }
t /                                   # 200
t /guides/deploying/                  # 200
t /guides/deploying                   # 301 https://docs.example.com/guides/deploying/
t /guides/deploying/index.html        # 301 https://docs.example.com/guides/deploying/
t "/guides/deploying?ref=nav"         # 301 .../deploying/?ref=nav
t /_astro/app.4f2a9c.js               # 200
t /does-not-exist/                    # 404

Add it to the post-deploy smoke tests so a function change that breaks one form fails the pipeline rather than the site. The general approach is in Running Smoke Tests Against a Preview URL.

Measured Impact

A 2,000-page docs site before and after the function, measured from CloudFront logs over a week and a crawl with a link checker.

Keeping the Generator and the Edge in Agreement

The function enforces a URL policy, but the generator produces the links, so the two must agree or every internal link costs a redirect. Check three places after changing either. Internal links in the built HTML should all use the canonical form; a crawl of the build output with a link checker configured to report redirects, not just errors, finds any stragglers — see Checking Links in Pull Requests. The sitemap should list only canonical URLs. And <link rel="canonical"> on each page should match the canonical form exactly. On this site, seven redirects per thousand requests remained after launch; all came from external links and old bookmarks, which is the expected residual.

Pitfalls & Rollback

• Using the S3 website endpoint. It solves index documents but forces a public, HTTP-only bucket. Use the REST endpoint with a function.
• Rewriting assets. Paths with a file extension must pass through unchanged; appending /index.html to app.js breaks every script.
• Dropping query strings in redirects. Preserve them, or tracking parameters and search deep links break.
• Year-long 301 caching. Keep redirect cache lifetimes short enough to correct a mistake.
• Rollback: disassociate the function from the cache behaviour. The change propagates in about a minute; publish a previous function version to restore it.

Conclusion

S3 does not know that /guides/ means guides/index.html; a twenty-line CloudFront Function teaches it, enforces one trailing-slash form with a single redirect, and costs a fraction of a millisecond per request. Pair it with a 403-to-404 mapping for missing pages and a smoke test that exercises every URL form, and a private S3 bucket serves a generator's directory-style output exactly as a managed host would.

FAQ

Why does /guides/ return an error on S3?

S3 is a key-value store. The REST endpoint looks for an object whose key is exactly guides/, which does not exist; the file is guides/index.html. CloudFront's default root object only applies to the site root, not to subdirectories.

Should URLs end with a trailing slash?

Either form works as long as the site uses exactly one and redirects the other. Most static site generators default to trailing slashes because each page is a directory with an index.html, so trailing slashes usually need the fewest rewrites.

Is a CloudFront Function or Lambda@Edge better for this?

A CloudFront Function. URL rewriting is simple string handling, which Functions run at every edge location in under a millisecond at a fraction of Lambda@Edge's cost. Use Lambda@Edge only if you need network calls or larger code.

Do rewrites affect caching?

A viewer-request rewrite changes the URI before the cache lookup, so /guides/ and /guides/index.html share one cache entry. That is usually desirable, and it avoids storing the same page twice.

Related

• Parent: Self-Hosting Static Sites on S3, Nginx and Caddy — self-hosting options compared.
• CloudFront Functions for Redirects — adding a redirect map to the same function.
• Deploying a Static Site to S3 and CloudFront — the distribution this function attaches to.
• Keeping Redirects Working After an SSG Migration — URL parity during migrations.
• Migrating from Hugo to Astro Without Breaking URLs — trailing-slash settings per generator.