Add trailing-slash redirects, 404 page, and CloudFront error config

- CloudFront function now returns 301 redirect for trailing-slash URLs
  instead of silently rewriting (fixes duplicate content issue)
- Generate static 404.html at build time with proper noscript fallback
  and noindex meta (fixes soft 404s returning 200)
- Deploy workflow uploads 404.html to S3 with appropriate caching
- Updated setup-cloudfront.sh with custom error response instructions
  (404 → /404.html with HTTP 404 status)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gmoon

.github/workflows/deploy.yml

@@ -58,6 +58,10 @@ jobs:
             --include "*.html" \
             --cache-control "public, max-age=300, s-maxage=86400"
 
+          # 404 page: short cache like HTML
+          aws s3 cp dist/404.html s3://forkzero-web-prod/404.html \
+            --cache-control "public, max-age=300, s-maxage=86400"
+
           # Invalidate CloudFront
           aws cloudfront create-invalidation \
             --distribution-id ${{ secrets.CF_DISTRIBUTION_ID }} \

infra/cloudfront-url-rewrite.js

@@ -1,13 +1,15 @@
 /**
- * CloudFront Function (viewer-request): rewrite clean URLs to /index.html.
+ * CloudFront Function (viewer-request): rewrite clean URLs to /index.html
+ * and redirect trailing slashes to their canonical non-trailing form.
  *
  * Converts paths like /blog/my-post → /blog/my-post/index.html so that
  * S3 REST API origin resolves pre-rendered HTML files.
  *
+ * - Redirects trailing slashes: /blog/ → 301 → /blog
  * - Skips URIs that already have a file extension (.js, .css, .xml, etc.)
  * - Skips root "/" (handled by CloudFront Default Root Object)
- * - Non-pre-rendered routes still work: S3 returns 404 → CloudFront custom
- *   error response serves the SPA shell (/index.html with 200).
+ * - Non-pre-rendered routes: S3 returns 404 → CloudFront custom error
+ *   response serves /404.html with HTTP 404.
  *
  * Runtime: cloudfront-js-2.0
  */
@@ -25,10 +27,19 @@ function handler(event) {
     return request;
   }
 
-  // Strip trailing slash, then append /index.html
+  // Redirect trailing slash to non-trailing (301)
   if (uri.endsWith('/')) {
-    uri = uri.slice(0, -1);
+    return {
+      statusCode: 301,
+      statusDescription: 'Moved Permanently',
+      headers: {
+        location: { value: uri.slice(0, -1) },
+        'cache-control': { value: 'public, max-age=86400' },
+      },
+    };
   }
+
+  // Rewrite clean URL to /index.html for S3 lookup
   request.uri = uri + '/index.html';
 
   return request;

infra/setup-cloudfront.sh

@@ -121,6 +121,35 @@ fi
 
 echo "    Policy ID: ${POLICY_ID}"
 
+# ---- Custom Error Response: proper 404 page ----
+echo ""
+echo "==> Configuring custom error response for 404s"
+echo ""
+echo "NOTE: CloudFront custom error responses must be set via the distribution"
+echo "config (not a standalone resource). Run the following to update it:"
+echo ""
+echo "  DIST_ID=your-distribution-id"
+echo ""
+echo '  # Get current config'
+echo '  aws cloudfront get-distribution-config --id $DIST_ID > /tmp/cf-config.json'
+echo '  ETAG=$(jq -r .ETag /tmp/cf-config.json)'
+echo ""
+echo '  # Extract DistributionConfig and add custom error response'
+echo '  jq ".DistributionConfig.CustomErrorResponses = {'
+echo '    \"Quantity\": 1,'
+echo '    \"Items\": [{'
+echo '      \"ErrorCode\": 404,'
+echo '      \"ResponsePagePath\": \"/404.html\",'
+echo '      \"ResponseCode\": \"404\",'
+echo '      \"ErrorCachingMinTTL\": 300'
+echo '    }]'
+echo '  } | .DistributionConfig" /tmp/cf-config.json > /tmp/cf-update.json'
+echo ""
+echo '  aws cloudfront update-distribution \'
+echo '    --id $DIST_ID \'
+echo '    --distribution-config file:///tmp/cf-update.json \'
+echo '    --if-match $ETAG'
+
 # ---- Instructions ----
 echo ""
 echo "==========================================================================="
@@ -131,12 +160,19 @@ echo "2. Edit the Default Cache Behavior:"
 echo "   a. Function associations → Viewer request → CloudFront Functions"
 echo "      → Select '${FUNCTION_NAME}'"
 echo "   b. Response headers policy → Select '${HEADERS_POLICY_NAME}'"
-echo "3. Save and wait for deployment to complete"
+echo "3. Configure Custom Error Response (Error Pages tab):"
+echo "   a. Error code: 404"
+echo "   b. Customize error response: Yes"
+echo "   c. Response page path: /404.html"
+echo "   d. HTTP response code: 404"
+echo "   e. Error caching minimum TTL: 300"
+echo "4. Save and wait for deployment to complete"
 echo ""
-echo "Or via CLI (replace DIST_ID and BEHAVIOR_CONFIG):"
+echo "Or via CLI (replace DIST_ID):"
 echo "  aws cloudfront get-distribution-config --id DIST_ID > dist-config.json"
 echo "  # Edit DefaultCacheBehavior to add:"
 echo "  #   FunctionAssociations with ${FUNCTION_ARN}"
 echo "  #   ResponseHeadersPolicyId: ${POLICY_ID}"
+echo "  # Edit CustomErrorResponses to add 404 → /404.html mapping"
 echo "  aws cloudfront update-distribution --id DIST_ID --distribution-config file://dist-config.json --if-match ETAG"
 echo "==========================================================================="

scripts/prerender.ts

@@ -112,6 +112,27 @@ for (const route of routes) {
   console.log(`Pre-rendered: ${route.path}`)
 }
 
+// --- Generate 404.html ---
+{
+  let html404 = template
+  html404 = html404.replace(/<title>.*?<\/title>/, '<title>Page not found — Forkzero</title>')
+  html404 = html404.replace(
+    /<meta name="description" content=".*?".*?\/?>/,
+    '<meta name="description" content="The page you are looking for does not exist." />',
+  )
+  const seoTags404 = [
+    '<meta name="robots" content="noindex" />',
+    '<meta property="og:title" content="Page not found — Forkzero" />',
+    '<meta property="og:type" content="website" />',
+    '<meta property="og:site_name" content="Forkzero" />',
+  ].join('\n    ')
+  html404 = html404.replace('</head>', `    ${seoTags404}\n  </head>`)
+  const noscript404 = `<noscript><div style="max-width:800px;margin:0 auto;padding:4rem 2rem;font-family:sans-serif;text-align:center"><h1>Page not found</h1><p>The page you're looking for doesn't exist or has been moved.</p><p><a href="/">Back to homepage</a></p></div></noscript>`
+  html404 = html404.replace('<div id="root"></div>', `<div id="root"></div>\n    ${noscript404}`)
+  writeFileSync(join(distDir, '404.html'), html404)
+  console.log('Generated: /404.html')
+}
+
 // --- Generate sitemap.xml ---
 // Note: <changefreq> and <priority> are ignored by Google and omitted per best practice.
 const today = new Date().toISOString().split('T')[0]