Site edge redirects and 404
Real 301 redirects and true 404 responses at the CloudFront edge for static sites: canonical host, clean URLs, custom rules and a not-found page.
Real 301s at the CloudFront edge for static sites — no JS/meta-refresh hacks, works for all crawlers. Opt-in: without these keys nothing changes. Applied on openkbs site deploy (propagation takes a few minutes).
Configuration
{
"site": "./site",
"redirects": {
"canonicalHost": "apex",
"cleanUrls": true,
"rules": [
{ "from": "/old-blog/*", "to": "/blog/:splat", "status": 301 }
]
},
"notFound": "/404.html"
}| Key | Effect |
|---|---|
redirects.canonicalHost | "apex" 301s www.example.com → example.com; "www" the reverse. Query string preserved. Needs an apex custom domain (ignored with a warning until one exists, and for subdomain hosts like app.example.com which have no www). |
redirects.cleanUrls | 301s /page.html → /page and /dir/index.html → /dir/, and internally rewrites /page → /page.html at the edge — so ship ONLY .html files, no extensionless duplicate copies. Directory pages are safe: /docs 301s to /docs/ (the CLI sends the site's directory list on deploy). |
redirects.rules | Up to 50 custom rules. from is an exact path or a prefix with trailing *; to is a path or https URL, :splat inserts the wildcard match; status 301 (default) or 302. Obvious loops are rejected at deploy. |
notFound | Unknown URLs serve this page with a real HTTP 404 (fixes soft-404s). Mutually exclusive with spa — an SPA needs 200 fallbacks. |
SEO recipe for a plain static site
Use canonicalHost + cleanUrls + notFound, then list extensionless duplicate files with openkbs site prune and delete them by name with site rm, and keep internal links extensionless.
Removing a config
To remove a previously applied config set "redirects": {} and deploy; removing notFound restores the default 200 fallback on the next deploy.
Redirects run in a sandboxed CloudFront Function on your own distribution only; a broken config can never affect other projects.