SSG Performance on AWS: Atomic Deploys, Edge Functions, and Pre-Compression

Static site generation (SSG) only looks like “compile, upload, done” until the second time you have to roll back at 02:00 with traffic on top of half-cached assets. This article is the production playbook for serving an SSG build through Amazon S3 and CloudFront: how to lay out atomic versioned deploys, when to choose CloudFront Functions over Lambda@Edge, how to pre-compress with Brotli without breaking content negotiation, how to use the native CloudFront Continuous Deployment feature for blue/green releases, and what an SSG site can actually do about Cumulative Layout Shift.

Thesis

Three architectural decisions compound to determine an SSG site’s TTFB, blast radius, and cost:

1. Where the work happens. Build-time rendering moves database queries, template expansion, and asset minification out of the request path. Origin servers shrink to file delivery and the CDN does the rest.
2. How releases are structured. Versioned, immutable build prefixes in S3 make rollback a configuration change instead of a redeploy. Object-level S3 Versioning is the wrong tool for application rollback.
3. Where logic lives at the edge. CloudFront Functions at 0.60 per 1M handles anything that needs the network or response body. Picking the wrong one wastes money or boxes you out of capabilities you’ll need.

Core Web Vitals thresholds at the 75th percentile, as of 2026: LCP ≤ 2.5 s, CLS ≤ 0.1, INP ≤ 200 ms (INP replaced FID on 2024-03-12⁴). These are the floor an SSG architecture should aim past, not the ceiling.

Mental model: SSG vs SSR vs ISR vs CSR

A senior team rarely picks one rendering mode for a whole product — modern frameworks (Next.js 15, Astro 5, SvelteKit) let you mix per route. Pick mode by data freshness and personalization cost, not by ideology.

Next.js 15’s per-route ISR is the revalidate route segment config (or the cacheLife({ revalidate, expire, stale }) function under the new Cache Components model)⁵. Astro 5 layers Server Islands on top of static islands so a marketing page can stream a personalized header without hydrating the whole tree⁶.

The article from here on assumes pure SSG output served from S3 + CloudFront with optional edge functions. Hybrid frameworks plug in cleanly because the deployment substrate is the same.

Atomic, versioned deployments

The pattern that actually works in production: every CI build uploads to a unique prefix in the bucket, and CloudFront points at that prefix.

1s3://my-site/2├── build_001/3│   ├── index.html4│   └── assets/...5├── build_002/6│   ├── index.html7│   └── assets/...8└── build_003/9    ├── index.html10    └── assets/...

You can index by semver, by release tag, or by the short Git SHA — the only requirement is uniqueness and immutability. Once build_002/ is closed, you never overwrite an object inside it. Rollback is a change to which prefix CloudFront resolves.

There are two ways to wire CloudFront to a prefix:

1. Origin path. Set the distribution’s origin path to /build_002. Update via UpdateDistribution. This is the simplest pattern and works on a single distribution.
2. Custom origin header + edge function. Send a header like x-build-version: build_002 from the origin configuration; an edge function rewrites the request URI to /${header}/${path}. This indirection makes A/B testing and gradual rollouts possible without a CloudFront config change per release.

The second pattern is more flexible but adds a function and the failure modes that come with it. For most SSG sites the origin path is enough; reach for the header indirection when you actually need cookie- or weight-based routing.

Cache invalidation cost mechanics

CloudFront prices invalidation by paths submitted per month, not by objects matched. The first 1,000 paths per month are free; beyond that each path is $0.005, and a wildcard like /* counts as one path regardless of how many objects it expands to⁷. A team deploying three times a day with a single /* invalidation per release submits 90 paths/month — comfortably inside the free tier.

The trap is doing fine-grained invalidations because “wildcard feels too broad”. Submitting 500 explicit paths per deploy puts you over the free tier on day 7.

Lifecycle and storage cost

Retain the last N versions you might roll back to (5–10 is normal), then expire the rest with an S3 lifecycle rule. A two-week trailing window covers nearly all “we need to revert that release” cases. For compliance-driven retention, ship the long tail to Glacier — never leave it in STANDARD.

Edge logic: CloudFront Functions vs Lambda@Edge

The two AWS edge compute primitives look interchangeable on a slide. They are not — one runs on every POP for sub-millisecond rewrites, the other ferries arbitrary Node/Python code to a smaller pool of regional caches⁸.

A 6× cost gap may be invisible at 10M req/month (6 plus duration) but it shows up at 10B. More importantly, the capability split is asymmetric: anything that needs a DNS lookup, a DynamoDB read, or to inspect the response body forces Lambda@Edge.

Operational footguns

Other watchouts:

• CloudWatch logs land in the executing region, not in us-east-1. Centralize log aggregation up front or you’ll hunt logs across 15 regions during incident triage.
• Cold starts are real for Lambda@Edge but bounded — replicas warm quickly under steady traffic. Build the cold-start latency into your p99 budget, not just p50.
• CloudFront Functions runs a restricted JavaScript runtime. cloudfront-js-2.0 adds let, const, arrow functions, template literals, async/await (inside async functions), Object.assign, globalThis, atob/btoa, and the Buffer module on top of ES 5.1; cloudfront-js-1.0 is ES 5.1 plus a small ES6–ES9 sliver and lacks all of the above. Pin the runtime in your function metadata and lint against the documented feature list — there is no network access, no file system, and no setTimeout/setInterval in either version¹¹.

Build-version routing example

Show 5 hidden lines6  const request = event.Records[0].cf.request7  const headers = request.headers8  const version = headers["x-build-version"]?.[0]?.value || "build_004"910  request.uri = request.uri === "/" ? `/${version}/index.html` : `/${version}${request.uri}`11  callback(null, request)12}

Pair this with a deploy script that updates the custom origin header on the distribution config:

Show 6 hidden lines7etag=$(aws cloudfront get-distribution-config --id "$distribution_id" --query 'ETag' --output text)8aws cloudfront update-distribution \9  --id "$distribution_id" \10  --distribution-config "file://dist-config-${version}.json" \11  --if-match "$etag"12aws cloudfront create-invalidation --distribution-id "$distribution_id" --paths "/*"

The same shape underpins blue/green and canary patterns later — a single header drives the routing.

Origin Shield: when the second hop pays for itself

Origin Shield inserts a centralized regional cache between the regional edge caches and your origin. When ten POPs miss the same uncached object simultaneously, Origin Shield collapses them into a single origin fetch, then fans the response back out.

Enable when:

• Your traffic is global enough that simultaneous-miss thundering herds reach S3.
• Your origin sees enough request volume that S3 GET costs are noticeable.
• Cache hit ratio is < 90% and you’ve already exhausted cache-policy and TTL tuning.

Skip when traffic is regional or origin cost is dominated by data transfer (Origin Shield doesn’t change egress).

Pre-compression: serving Brotli without breaking caches

CloudFront will compress on the fly. The catch list is long enough that pre-compressing at build time is the durable answer for any non-trivial SSG site.

CloudFront automatic compression — the catch list

CloudFront’s edge compression is governed by enough rules that it silently fails for plenty of real assets:

• Object size: only 1 KB to 10 MB is compressed. Outside that range CloudFront serves identity, full stop.
• Origin headers: if your origin already sets Content-Encoding, CloudFront assumes the object is pre-compressed and never re-compresses.
• HTTPS-only Brotli: browsers send Accept-Encoding: br only over HTTPS. Plain HTTP gets gzip at best¹².
• HTTP/1.0: CloudFront strips Accept-Encoding for HTTP/1.0 viewer requests, disabling compression entirely.
• Status codes: only 200, 403, and 404 responses are eligible.
• Cache key: you must use a cache policy with EnableAcceptEncodingGzip and EnableAcceptEncodingBrotli set to true; legacy cache settings cannot select Brotli.
• TTL > 0: disabled cache means no compression.
• Best effort under load: CloudFront documents that it may skip compression when stressed.
• No retroactive compression: objects already in the cache are not compressed when you flip the toggle. You must invalidate them.

Brotli vs Gzip in real numbers, based on Cloudflare’s published benchmarks: Brotli Q11 yields roughly 14–20% smaller JS and HTML and 17–30% smaller CSS than Gzip -9, with comparable decompression speed¹³. Over 96% of browsers accept br¹⁴, and the long tail still falls back to gzip.

Build-time pipeline

Compress in CI to the maximum quality your build budget allows. Q11 on a 1.6 MB JS bundle is on the order of 1–2 seconds; that’s a one-time cost amortized across every viewer.

1# Run after the bundler emits final assets; produces sibling .br and .gz files.2find dist -type f \( -name "*.js" -o -name "*.css" -o -name "*.html" -o -name "*.svg" \) -print0 |3  while IFS= read -r -d '' f; do4    brotli -q 11 -k -o "${f}.br" "$f"5    gzip   -9  -k          "$f"6  done

Upload each variant with the right Content-Encoding so CloudFront does not re-encode:

1aws s3 cp dist/main.js     s3://bucket/build_007/main.js     --content-type application/javascript2aws s3 cp dist/main.js.br  s3://bucket/build_007/main.js.br  --content-type application/javascript --content-encoding br3aws s3 cp dist/main.js.gz  s3://bucket/build_007/main.js.gz  --content-type application/javascript --content-encoding gzip

Edge content negotiation

A small CloudFront Function on the viewer-request trigger picks the variant. CloudFront Functions handles this in microseconds at every POP for $0.10/1M; Lambda@Edge would also work but is overkill.

1// CloudFront Function — viewer-request trigger.2// Picks the best precomputed variant available based on the viewer's3// Accept-Encoding. Cache key must include Accept-Encoding to keep variants4// segregated.5function handler(event) {6  var req = event.request7  var ae = (req.headers["accept-encoding"] && req.headers["accept-encoding"].value) || ""8  if (!/\.(?:js|css|html|svg|json)$/.test(req.uri)) return req910  if (ae.indexOf("br") !== -1) {11    req.uri = req.uri + ".br"12  } else if (ae.indexOf("gzip") !== -1) {13    req.uri = req.uri + ".gz"14  }15  return req16}

CloudFront cache-policy configuration that pairs with this:

• Include Accept-Encoding in the cache key (one entry per encoding).
• Disable “Compress Objects Automatically” (you’ve taken over).
• Forward Accept-Encoding in the origin request policy.

Indicative impact

Real numbers vary with content but the directional pattern holds: an SSG bundle that ships at ~3.5 MB uncompressed typically lands around ~250 KB Brotli Q11 (≈14:1) and ~460 KB Gzip -9 (≈8:1). Over a fast 4G link that translates to roughly half the load time at the same cache layer.

CloudFront Continuous Deployment for blue/green

For most blue/green rollouts on CloudFront, the right answer is no longer custom Lambda@Edge cookie routing. AWS shipped CloudFront Continuous Deployment in late 2022: a managed staging distribution paired with the primary distribution via a continuous deployment policy, with weight-based or session-stickiness traffic splits³. That removes a piece of custom code that was famously easy to break.

Use it when:

• You want to test a CloudFront configuration change (cache policy, origin, function association) on a slice of real traffic before promoting.
• You want session-sticky canaries so the same viewer keeps hitting the same distribution.
• You want native CloudWatch metrics on both distributions during the canary.

Don’t use it for:

• Permanent multi-distribution traffic split (it’s designed for promotion, not steady-state routing).
• Geographic or per-user routing — those still belong in Lambda@Edge or in DNS-level routing (Route 53 weighted records, Global Accelerator).

Lambda@Edge cookie routing — when you actually need it

The Lambda@Edge pattern is still the right call when:

• You need cookie- or header-driven routing across more than two backends (Continuous Deployment is two distributions only).
• You need cohort logic (geo, IP hash, account ID) that isn’t expressible as a weight or sticky header.
• You’re running a multi-tenant CDN where the routing logic is data-driven from a database.

Show 4 hidden lines56exports.handler = async (event) => {7  const request = event.Records[0].cf.request8  const cookies = request.headers.cookie || []9  const wantsGreen = cookies.some(c => c.value.includes("routing=green"))10  const target = wantsGreen ? green : blue1112  request.origin.s3.domainName = target13  request.headers.host = [{ key: "Host", value: target }]14  return request15}

The cookie is set elsewhere — typically a CloudFront Function on the viewer-response of a “join the green canary” page, or a logged-in user setting via your application.

Canary by IP hash

For percentage-based canaries with session stickiness, hash a stable identifier (the client IP from x-forwarded-for, an account ID from a JWT) modulo 100 and route based on the bucket:

Show 4 hidden lines5const CANARY = "canary-bucket.s3.amazonaws.com"6const CANARY_PCT = 1078exports.handler = async (event) => {9  const request = event.Records[0].cf.request10  const ip = request.headers["x-forwarded-for"]?.[0]?.value || "0.0.0.0"11  const bucket = ip.split(".").reduce((a, b) => a + parseInt(b, 10), 0) % 10012  request.origin.s3.domainName = bucket < CANARY_PCT ? CANARY : PROD13  return request14}

Tie automatic rollback to a CloudWatch alarm on canary error rate or LCP regression — the human in the loop should be the exception, not the path.

CLS budget on a static site

Raw delivery speed is a prerequisite, not the goal. Visual stability is what users perceive. CLS aggregates unexpected shifts during the page lifecycle; a fast page that pops and reflows is worse than a slightly slower page that doesn’t.

What actually shifts on a static page

Most CLS regressions on SSG sites trace to four sources:

1. Images without intrinsic dimensions. The browser reserves zero space until decode; everything below moves when the image arrives.
2. Late-injected embeds. Ads, social cards, YouTube iframes, cookie banners arrive after the first paint and push content down.
3. Web font swap. The fallback metric and the loaded font have different x-heights and advance widths, causing line-break reflows.
4. Client hydration that mounts components only on the client. Anything rendered with client:only (Astro) or dynamic(... { ssr: false }) (Next) starts as a hole.

For attribution at runtime, the Layout Instability API exposes LayoutShift.sources — an array of up to five LayoutShiftAttribution objects sorted by impact area; if more than five elements participated in a shift, the largest five are kept¹⁵. sources[0] is your worst offender.

Mitigations

1<img2  src="/assets/hero-1280.jpg"3  width="1280"4  height="720"5  alt="A close-up of a sleeping cat."6  style="width: 100%; height: auto;"7/>

The intrinsic width and height give the browser an aspect ratio it can reserve before the bytes land. style="width: 100%; height: auto" keeps it responsive without surrendering the reservation.

For variable-size embeds, reserve the most-common dimension with min-height:

1<div style="min-height: 250px;">2  <!-- Display ad mounts here after script loads -->3</div>

Fonts: preload the critical face and pick a fallback with similar metrics (size-adjust, ascent-override, descent-override, line-gap-override in @font-face):

1<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>2<style>3  @font-face {4    font-family: "Inter";5    src: url("/fonts/inter-var.woff2") format("woff2");6    font-display: swap;7    size-adjust: 100.5%;8    ascent-override: 90%;9    descent-override: 22%;10    line-gap-override: 0%;11  }12</style>

font-display: swap keeps text visible during font load (better LCP) at the cost of a swap-time shift; optional removes the shift but accepts that some viewers never see your font on the first visit. Pick based on the metric mismatch and how visible the typography is.

Dual-build for divergent mobile/desktop layouts

When mobile and desktop layouts produce different above-the-fold heights for the same components, a single SSG build forces one of them to shift on hydration. Two builds — separate routes for /mobile/* and /desktop/* — let each viewer get the right pre-rendered HTML.

The routing belongs in an edge function and the cache key needs to include the device dimension:

1// Lambda@Edge — origin-request trigger.2// Routes /mobile/* or /desktop/* based on CloudFront's device header.3exports.handler = async (event) => {4  const req = event.Records[0].cf.request5  const isMobile = req.headers["cloudfront-is-mobile-viewer"]?.[0]?.value === "true"6  const prefix = isMobile ? "/mobile" : "/desktop"7  req.uri = req.uri === "/" ? `${prefix}/index.html` : `${prefix}${req.uri}`8  return req9}

The corresponding cache policy must include CloudFront-Is-Mobile-Viewer (and any other dimensions you route on) in the cache key, otherwise mobile and desktop variants collide. CloudFront’s CloudFront-Is-*-Viewer headers normalize User-Agent into a small set of booleans precisely so device-aware caching doesn’t shred your hit ratio¹⁶.

URL redirects at the edge

Three options, each with a sharp constraint:

S3’s RoutingRules come with two structural limits that disqualify them for production SSG sites: 50 rules per bucket¹⁷, and they only work with the public S3 website endpoint — the moment you adopt Origin Access Control (OAC) to lock the bucket down, you lose both routing rules and automatic index.html resolution¹⁸.

For a small, static map of /old → /new redirects, a CloudFront Function is plenty:

1// CloudFront Function — viewer-request trigger.2// Issues a 301 from a static lookup table; falls through to the cache otherwise.3var REDIRECTS = {4  "/old-product": { to: "/new-product", code: 301 },5  "/promo":       { to: "/current-sale", code: 302 },6  "/legacy-docs": { to: "https://docs.example.com", code: 301 },7}89function handler(event) {10  var req = event.request11  var rule = REDIRECTS[req.uri]12  if (!rule) return req13  return {14    statusCode: rule.code,15    statusDescription: rule.code === 301 ? "Moved Permanently" : "Found",16    headers: {17      "location":      { value: rule.to },18      "cache-control": { value: "max-age=3600" },19    },20  }21}

Move to Lambda@Edge only when you need a redirect map larger than a single function deployment can hold (a DynamoDB lookup), or when the redirect target depends on geo or auth state.

Operational defaults

Decisions worth making once and revisiting only on signal:

• Versioned S3 prefix per build, lifecycle out at 14 days, retain last 5–10 explicitly. Don’t run application rollback through S3 Object Versioning.
• Single CloudFront distribution for the main site. Use Continuous Deployment for canaries; reach for a second distribution only when the routing genuinely doesn’t fit a single config.
• Pre-compress at build (Brotli Q11 + Gzip -9), serve via edge content negotiation. CloudFront’s automatic compression has too many silent skips for assets that matter.
• Cache policy with Accept-Encoding in the cache key, Origin Request Policy forwarding only what you actually use. Every extra cache-key dimension is a hit-ratio loss.
• Lambda@Edge replicas live in us-east-1; centralize CloudWatch logs early. Do not discover this during an incident.
• Reserve dimensions for everything that loads asynchronously. Images get width/height; ad slots get min-height; fonts get size-adjust overrides.
• Wire automatic rollback to CloudWatch alarms on Lambda@Edge errors, CloudFront 5xx rate, and synthetic CWV regressions. Manual rollback is the failure mode, not the goal.

Appendix

Glossary

• TTFB (Time to First Byte) — interval from request initiation to the first response byte.
• LCP (Largest Contentful Paint) — render time of the largest image or text block in the viewport. Good ≤ 2.5 s at p75.
• CLS (Cumulative Layout Shift) — sum of unexpected layout shifts across the page lifecycle. Good ≤ 0.1 at p75.
• INP (Interaction to Next Paint) — latency of the worst (or near-worst) user interaction. Replaced FID on 2024-03-12. Good ≤ 200 ms at p75.
• ISR (Incremental Static Regeneration) — regenerating a static page on demand after a revalidate interval. Next.js native; emulated by other frameworks via cron or webhooks.
• OAC (Origin Access Control) — CloudFront mechanism that signs origin requests so an S3 bucket can refuse public access.
• POP (Point of Presence) — physical location where CloudFront accepts viewer connections. Distinct from regional edge caches.
• Regional Edge Cache (REC) — second-tier CloudFront cache; Lambda@Edge runs here.
• Origin Shield — optional centralized regional cache between RECs and origin; collapses simultaneous misses.