CloudFront Invalidation With AWS SDK v3 (CreateInvalidation)

// invalidate.ts: invalidate two paths on a CloudFront distribution and wait until it has completed.
// Usage: DISTRIBUTION_ID=E2QWRUHAPOMQZL npx tsx invalidate.ts
import { CloudFrontClient, CreateInvalidationCommand, waitUntilInvalidationCompleted } from "@aws-sdk/client-cloudfront";

const client = new CloudFrontClient({ region: "us-east-1" }); // CloudFront is global; any Region works
const DistributionId = process.env.DISTRIBUTION_ID ?? "E2QWRUHAPOMQZL";
const paths = ["/index.html", "/css/*"]; // API paths must start with "/"; "*" only at the end

const { Invalidation } = await client.send(new CreateInvalidationCommand({
  DistributionId,
  InvalidationBatch: {
    CallerReference: `deploy-${Date.now()}`, // new value for every new invalidation
    Paths: { Quantity: paths.length, Items: paths },
  },
}));
console.log(`Invalidation ${Invalidation?.Id} is ${Invalidation?.Status}`);

await waitUntilInvalidationCompleted(
  { client, maxWaitTime: 900 }, // seconds; polls GetInvalidation every 20 s or more
  { DistributionId, Id: Invalidation?.Id ?? "" },
);
console.log(`Invalidation ${Invalidation?.Id} is Completed`);

Invalidation IX2QXVKEXAMPLE is InProgress
Invalidation IX2QXVKEXAMPLE is Completed

// cloudfront-invalidate.ts: normalize paths, create an idempotent invalidation, retry when too many
// invalidations are in progress, and optionally wait for it to complete.
import { createHash } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";
import {
  CloudFrontClient,
  CreateInvalidationCommand,
  TooManyInvalidationsInProgress,
  waitUntilInvalidationCompleted,
} from "@aws-sdk/client-cloudfront";

export interface InvalidateOptions {
  /** Stable ID for this logical change, such as a deploy ID or commit SHA. Retries reuse it. */
  reference: string;
  /** Collapse to one wildcard path when there are more than this many paths (each path is billed). */
  maxPaths?: number;
  /** Seconds to wait for completion; 0 returns as soon as the invalidation is created. */
  waitSeconds?: number;
}

/** Turn object keys or URL paths into CloudFront invalidation paths. */
export function toInvalidationPaths(keysOrPaths: string[]): string[] {
  const out = new Set<string>();
  for (const raw of keysOrPaths) {
    if (raw.startsWith("#")) { // cache tag invalidation; needs CacheTagConfig on the distribution
      out.add(raw);
      continue;
    }
    if (raw.includes("~")) throw new Error(`CloudFront can't invalidate paths containing "~": ${raw}`);
    const path = raw.startsWith("/") ? raw : `/${raw}`;
    out.add(encodeURI(path)); // encodes spaces and non-ASCII characters; keeps "/", "*" and "?"
  }
  return [...out].sort();
}

export async function invalidate(
  client: CloudFrontClient,
  distributionId: string,
  keysOrPaths: string[],
  opts: InvalidateOptions,
): Promise<{ id: string; status: string; paths: string[] }> {
  let paths = toInvalidationPaths(keysOrPaths);
  if (paths.length === 0) throw new Error("nothing to invalidate");
  if (opts.maxPaths !== undefined && paths.length > opts.maxPaths) paths = ["/*"];

  // Same reference + same paths = same CallerReference, so a retried deploy returns the
  // existing invalidation instead of creating (and paying for) a second one.
  const digest = createHash("sha256").update(paths.join("\n")).digest("hex").slice(0, 16);
  const CallerReference = `${opts.reference}-${digest}`;

  for (let attempt = 1; ; attempt++) {
    try {
      const { Invalidation } = await client.send(new CreateInvalidationCommand({
        DistributionId: distributionId,
        InvalidationBatch: { CallerReference, Paths: { Quantity: paths.length, Items: paths } },
      }));
      const id = Invalidation?.Id ?? "";
      if (opts.waitSeconds) {
        await waitUntilInvalidationCompleted({ client, maxWaitTime: opts.waitSeconds }, { DistributionId: distributionId, Id: id });
        return { id, status: "Completed", paths };
      }
      return { id, status: Invalidation?.Status ?? "", paths };
    } catch (err) {
      if (!(err instanceof TooManyInvalidationsInProgress) || attempt >= 5) throw err;
      const delay = 2 ** attempt * 1000 + Math.floor(Math.random() * 1000);
      console.warn(`too many invalidations in progress, retrying in ${Math.round(delay / 1000)} s`);
      await sleep(delay);
    }
  }
}

// deploy-site.ts: upload a built static site to S3, then invalidate only the files whose names
// don't change between builds. Fingerprinted assets (app.3f9c2b1e.js) get a long cache lifetime
// and are never invalidated.
// Usage: BUCKET=www.example.com DISTRIBUTION_ID=E2QWRUHAPOMQZL DEPLOY_ID=$(git rev-parse --short HEAD) npx tsx deploy-site.ts ./dist
import { readdir, readFile } from "node:fs/promises";
import { extname, join, relative, sep } from "node:path";
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { CloudFrontClient } from "@aws-sdk/client-cloudfront";
import { invalidate } from "./cloudfront-invalidate.js";

const root = process.argv[2] ?? "./dist";
const bucket = process.env.BUCKET ?? "www.example.com";
const distributionId = process.env.DISTRIBUTION_ID ?? "E2QWRUHAPOMQZL";
const deployId = process.env.DEPLOY_ID ?? `local-${Date.now()}`;

const TYPES: Record<string, string> = {
  ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript",
  ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".txt": "text/plain",
  ".xml": "application/xml", ".woff2": "font/woff2",
};
const FINGERPRINTED = /\.[0-9a-f]{8,}\.[a-z0-9]+$/i; // app.3f9c2b1e.js, logo.a1b2c3d4e5.svg

async function* walk(dir: string): AsyncGenerator<string> {
  for (const entry of await readdir(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) yield* walk(full);
    else yield full;
  }
}

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "us-east-1" });
const toInvalidate: string[] = [];
let uploaded = 0;

for await (const file of walk(root)) {
  const key = relative(root, file).split(sep).join("/");
  const hashed = FINGERPRINTED.test(key);
  await s3.send(new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    Body: await readFile(file),
    ContentType: TYPES[extname(key).toLowerCase()] ?? "application/octet-stream",
    CacheControl: hashed ? "public, max-age=31536000, immutable" : "public, max-age=60",
  }));
  uploaded += 1;
  if (!hashed) toInvalidate.push(key);
}

// "index.html" is also served as "/", so invalidate the directory form too.
const paths = toInvalidate.flatMap((k) => (k === "index.html" ? ["/", k] : k.endsWith("/index.html") ? [`/${k.slice(0, -10)}`, k] : [k]));
console.log(`uploaded ${uploaded} files; ${paths.length} paths need invalidating`);

const cloudfront = new CloudFrontClient({ region: "us-east-1" });
const result = await invalidate(cloudfront, distributionId, paths, { reference: deployId, maxPaths: 50, waitSeconds: 900 });
console.log(`invalidation ${result.id} ${result.status}: ${result.paths.join(" ")}`);

uploaded 7 files; 6 paths need invalidating
invalidation IX2QXVKEXAMPLE Completed: / /docs/ /docs/caf%C3%A9%20menu.html /docs/index.html /index.html /robots.txt

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InvalidateOneDistribution",
      "Effect": "Allow",
      "Action": [
        "cloudfront:CreateInvalidation",
        "cloudfront:GetInvalidation",
        "cloudfront:ListInvalidations"
      ],
      "Resource": "arn:aws:cloudfront::123456789012:distribution/E2QWRUHAPOMQZL"
    },
    {
      "Sid": "UploadSiteFiles",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::www.example.com/*"
    }
  ]
}