sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Website/ Nextjs.ts

import { AlchemyContext } from "alchemy/AlchemyContext";
import type { MemoOptions } from "alchemy/Command/Memo";
import type { InputProps } from "alchemy/Input";
import type { Input } from "alchemy/Input";
import * as Namespace from "alchemy/Namespace";
import * as Output from "alchemy/Output";
import { ProviderModePolicy } from "alchemy/ProviderMode";
import { Server, type ServerDevProps } from "alchemy/Website/Server";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import { Table } from "../DynamoDB/Table.ts";
import type { PolicyStatement } from "../IAM/Policy.ts";
import { EventSourceMapping } from "../Lambda/EventSourceMapping.ts";
import { Function as LambdaFunction } from "../Lambda/Function.ts";
import { WebFunction } from "../Lambda/WebFunction.ts";
import { Bucket } from "../S3/Bucket.ts";
import { Queue } from "../SQS/Queue.ts";
import { AssetDeployment } from "./AssetDeployment.ts";
import { asRouterDomain, registerDevRouterRoute } from "./DevRouterRoute.ts";
import {
  checkWebsiteRegions,
  siteEndpoint,
  type FunctionServerProps,
  type WebFunctionServerProps,
} from "./FrameworkSite.ts";
import {
  normalizeWebsiteDomain,
  type WebsiteAssetsConfig,
  type WebsiteDomainProps,
  type WebsiteEdgeProps,
  type WebsiteInvalidationProps,
} from "./shared.ts";
import { makeKvSite, type StaticSiteProps } from "./StaticSite.ts";

/**
 * The framework-integration module that drives the `@opennextjs/aws` build
 * (it is its own deploy target — the module IS the AWS pipeline).
 */
export const NEXTJS_AWS_FRAMEWORK_SPECIFIER = "@alchemy.run/frontend-frameworks/nextjs/aws";

/** The S3 key prefix of the Next.js cache (both server forms). */
export const NEXTJS_CACHE_PREFIX = "_cache";

/** Props shared by both server forms of {@link Nextjs}. */
export interface NextjsBaseProps {
  /**
   * Project root directory (the directory containing `next.config.ts`).
   * @default "."
   */
  rootDir?: string;
  /**
   * Controls which files are hashed to decide whether the build re-runs.
   * @default true
   */
  memo?: MemoOptions | boolean;
  /**
   * Options for the local dev server that runs this site under
   * `alchemy dev`.
   */
  dev?: ServerDevProps;
  /**
   * Maximum server request duration.
   * @default 30 seconds
   */
  timeout?: Duration.Duration;
  /**
   * Environment variables for the SSR server (Lambda environment).
   * Values accept `Output`s (e.g. `API_URL: api.url`).
   */
  env?: Record<string, any>;
  /**
   * Static asset upload configuration.
   */
  assets?: WebsiteAssetsConfig;
  /**
   * Optional custom domain. A string is shorthand for `{ name }`; `null`
   * explicitly clears a previously set domain. Set `domain.router` to
   * serve the site through an existing `AWS.Website.Router` instead of a
   * standalone CloudFront distribution.
   */
  domain?: string | WebsiteDomainProps | null;
  /**
   * Serve the site at its CloudFront default domain
   * (`https://dxxxx.cloudfront.net`). `false` 301s default-domain requests
   * to `https://<domain.name>` at the edge and excludes the default domain
   * from the `urls` output. Requires `domain`; not applicable when
   * `domain.router` is set.
   * @default true
   */
  cloudfrontUrl?: boolean;
  /**
   * Additional CloudFront Function customizations.
   */
  edge?: WebsiteEdgeProps;
  /**
   * Optional deterministic S3 bucket name for the asset bucket.
   */
  bucketName?: string;
  /**
   * Whether to delete uploaded objects when the bucket is destroyed.
   * @default false
   */
  forceDestroy?: boolean;
  /**
   * CloudFront invalidation behavior.
   * @default { paths: "all", wait: false }
   */
  invalidation?: false | WebsiteInvalidationProps;
  /**
   * User-defined tags applied to created resources.
   */
  tags?: Record<string, string>;
}

/**
 * The server and the image optimizer on Lambda Functions behind Function
 * URLs: for servers that need more than 2 GB of memory or x86_64, or
 * Regions without Web Functions.
 */
export interface NextjsFunctionServerProps extends FunctionServerProps {
  /**
   * Image optimization (Lambda) configuration.
   */
  imageOptimization?: {
    /**
     * Memory allocated to the image optimization function, in MB.
     * @default 1536
     */
    memorySize?: number;
  };
}

/**
 * Props for {@link Nextjs}. By default Next runs as its standalone server on
 * a Lambda Web Function; set `server: "function"` for the OpenNext topology
 * on Lambda Functions.
 */
export type NextjsProps = NextjsBaseProps & (WebFunctionServerProps | NextjsFunctionServerProps);

/**
 * Deploy a Next.js application to AWS: Next's own standalone server on a
 * Lambda Web Function, static assets in S3 behind CloudFront's KV-manifest
 * edge router, and an S3 bucket for the cache. The server runs the way it
 * does under `next start` (SSR, middleware, ISR revalidation and
 * `/_next/image` in-process), and an S3 `cacheHandler` shares ISR pages,
 * the fetch cache and optimized images across environments.
 *
 * The build runs through `@alchemy.run/frontend-frameworks/nextjs/aws`,
 * which must be installed in your project. It runs `next build` with
 * standalone output; your `next.config.*` is used as-is.
 *
 * With `server: "function"` the site uses the OpenNext (`@opennextjs/aws`)
 * topology instead: the server and an image optimizer on Lambda Functions
 * behind streaming Function URLs, and ISR revalidation through an SQS FIFO
 * queue, a consumer Lambda, and a DynamoDB tag table. Install
 * `@opennextjs/aws` for it; when the project has no `open-next.config.ts`,
 * a minimal streaming default is generated.
 *
 * During `alchemy dev` the site is Next's own dev server (`next dev`) and
 * no cloud resources are declared; `Alchemy.remote()` opts back into the
 * full live deployment.
 *
 * ### Creating Next.js Sites
 * **Example:** Basic Next.js App
 * ```typescript
 * const site = yield* AWS.Website.Nextjs("Web", {
 *   rootDir: "./app",
 * });
 * ```
 *
 * **Example:** Custom Domain
 * ```typescript
 * const site = yield* AWS.Website.Nextjs("Web", {
 *   rootDir: "./app",
 *   domain: {
 *     name: "app.example.com",
 *     hostedZoneId: zone.hostedZoneId,
 *   },
 * });
 * ```
 *
 * ### Server Configuration
 * **Example:** Tune The Server Function
 * ```typescript
 * const site = yield* AWS.Website.Nextjs("Web", {
 *   rootDir: "./app",
 *   memorySize: 2048,
 *   env: {
 *     API_BASE: api.url,
 *   },
 * });
 * ```
 *
 * @resource
 */

export const Nextjs = Effect.fn("AWS.Website.Nextjs")(
  function* (id: string, propsIn: InputProps<NextjsProps, "server"> = {}) {
    const props = propsIn as NextjsProps;
    yield* checkWebsiteRegions(`AWS.Website.Nextjs "${id}"`, props);
    const ctx = yield* AlchemyContext;
    const remoted = yield* ProviderModePolicy;
    // Mirrors the other Website composites: during `alchemy dev` the site
    // is `next dev` (native HMR) and no cloud resources are declared;
    // `Alchemy.remote()` opts back into the full live deployment.
    const isLocal = ctx.dev && remoted !== true;
    const onWebFunction = (props.server ?? "web-function") === "web-function";

    const build = yield* Server("Build", {
      framework: NEXTJS_AWS_FRAMEWORK_SPECIFIER,
      target: NEXTJS_AWS_FRAMEWORK_SPECIFIER,
      options: { server: onWebFunction ? "web-function" : "function" },
      root: props.rootDir,
      env: props.env,
      memo: props.memo,
      dev: props.dev,
    });

    if (isLocal) {
      // Router-attached sites register with the Router in dev exactly as they
      // do live — same resource types and ids — with `next dev` standing in
      // for the S3 + Lambda origins.
      const routerDomain = asRouterDomain(normalizeWebsiteDomain(props.domain));
      const kvNamespace = routerDomain
        ? yield* registerDevRouterRoute(routerDomain, build.url)
        : undefined;
      return {
        bucket: undefined,
        build,
        cacheBucket: undefined,
        cacheFiles: undefined,
        distribution: undefined,
        files: undefined,
        imageFunction: undefined,
        imageUrl: undefined,
        invalidation: undefined,
        kvNamespace,
        revalidationFunction: undefined,
        revalidationQueue: undefined,
        server: undefined,
        serverUrl: undefined,
        tagCacheTable: undefined,
        url: build.url,
        urls: [build.url],
      };
    }

    // `.open-next/<relative>` derived from the build's dist directory.
    const fromDist = (relative: string) =>
      Output.map((dir: string | undefined) => {
        if (!dir) {
          throw new Error("The Next.js build produced no .open-next directory.");
        }
        return `${dir}/${relative}`;
      })(build.distDir as any) as Input<string>;

    // The CDN-facing asset bucket (site assets + public files + originals
    // for the image optimizer).
    const bucket =
      props.assets?.bucket ??
      (yield* Bucket("Bucket", {
        bucketName: props.bucketName,
        forceDestroy: props.forceDestroy,
        tags: props.tags,
      }));

    // The ISR/fetch cache lives in its OWN bucket, deliberately separate
    // from the site bucket: the site bucket carries the CloudFront read
    // policy (bound to the distribution's ARN), so a server -> site-bucket
    // reference would close a dependency cycle
    // (server -> bucket -> distribution -> server) and force the CloudFront
    // origin to rendezvous on the Lambda's precreate stub, which has no
    // Function URL yet. A dedicated cache bucket keeps the graph acyclic.
    const cacheBucket = yield* Bucket("CacheBucket", {
      forceDestroy: props.forceDestroy,
      tags: props.tags,
    });

    // The cache handler's S3 access, on whichever server runs.
    const cachePolicy = [
      {
        Effect: "Allow",
        Action: ["s3:GetObject", "s3:PutObject"],
        Resource: [Output.interpolate`${cacheBucket.bucketArn}/*` as any],
      },
      {
        // A missing key answers 404 (not 403) only with ListBucket.
        Effect: "Allow",
        Action: ["s3:ListBucket"],
        Resource: [cacheBucket.bucketArn as any],
      },
    ] satisfies PolicyStatement[];

    if (props.server !== "function") {
      // Next's standalone server: SSR, middleware, ISR revalidation and
      // `/_next/image` run in-process; the S3 cache handler shares the
      // cache across environments.
      const server = yield* WebFunction("WebServer", {
        main: build.serverEntry as unknown as string,
        bundle: false,
        authType: "ApplicationManaged",
        timeout: props.timeout ?? Duration.seconds(30),
        maxConcurrencyPerEnvironment: props.maxConcurrencyPerEnvironment,
        maxEnvironments: props.maxEnvironments,
        env: {
          CACHE_BUCKET_NAME: cacheBucket.bucketName,
          CACHE_BUCKET_KEY_PREFIX: NEXTJS_CACHE_PREFIX,
          ...props.env,
        },
      });
      yield* server.bind`Allow(${server}, AWS.Website.Nextjs.Cache(${cacheBucket}))`({
        policyStatements: cachePolicy,
      });
      const endpoint = yield* siteEndpoint("ServerEndpoint", server, props);
      const site = yield* makeKvSite(
        id,
        {
          path: build.clientDir as unknown as string,
          assets: props.assets,
          domain: props.domain,
          cloudfrontUrl: props.cloudfrontUrl,
          edge: props.edge,
          bucketName: props.bucketName,
          forceDestroy: props.forceDestroy,
          invalidation: props.invalidation,
          tags: props.tags,
        },
        { serverHost: endpoint.domainName },
      );
      return {
        ...site,
        build,
        cacheBucket,
        cacheFiles: undefined,
        imageFunction: undefined,
        imageUrl: undefined,
        revalidationFunction: undefined,
        revalidationQueue: undefined,
        server,
        serverUrl: endpoint.url,
        tagCacheTable: undefined,
      };
    }
    const fnProps = props;

    // ISR revalidation queue: OpenNext's `sqs` queue override sends
    // explicitly-deduplicated messages to a FIFO queue.
    const revalidationQueue = yield* Queue("RevalidationQueue", {
      fifo: true,
      // Lambda requires the queue's visibility timeout to cover the
      // consumer function's timeout (30s) with headroom.
      visibilityTimeout: "2 minutes",
      tags: props.tags,
    });

    // Tag cache (`revalidateTag` / `revalidatePath`): the schema OpenNext's
    // `dynamodb` tag-cache override queries — `tag`/`path` primary key plus
    // the `revalidate` GSI on `path`/`revalidatedAt`.
    const tagCacheTable = yield* Table("TagCache", {
      partitionKey: "tag",
      sortKey: "path",
      attributes: { tag: "S", path: "S", revalidatedAt: "N" },
      globalSecondaryIndexes: [
        {
          indexName: "revalidate",
          partitionKey: "path",
          sortKey: "revalidatedAt",
          projection: { ProjectionType: "ALL" },
        },
      ],
      billingMode: "PAY_PER_REQUEST",
      tags: props.tags,
    });

    const server = yield* LambdaFunction("Server", {
      // The framework module derives the entry from open-next.output.json
      // (origins.default.bundle + handler), so this tracks the manifest.
      main: build.serverEntry as unknown as string,
      handler: "handler",
      isExternal: true,
      // OpenNext's server-functions/default is a complete deployment unit
      // (entry + traced .next output + its own node_modules) — ship as-is.
      bundle: false,
      runtime: fnProps?.runtime ?? "nodejs24.x",
      architecture: fnProps?.architecture,
      memorySize: fnProps?.memorySize ?? 1024,
      timeout: props.timeout ?? Duration.seconds(30),
      env: {
        // The env names OpenNext's s3/sqs/dynamodb overrides read. Regions
        // are omitted: the SDK falls back to the Lambda runtime's own
        // AWS_REGION, and every resource here is same-region.
        CACHE_BUCKET_NAME: cacheBucket.bucketName,
        CACHE_BUCKET_KEY_PREFIX: NEXTJS_CACHE_PREFIX,
        REVALIDATION_QUEUE_URL: revalidationQueue.queueUrl,
        CACHE_DYNAMO_TABLE: tagCacheTable.tableName,
        ...props.env,
      },
      functionUrl: {
        authType: "NONE",
        // The default server is built with the aws-lambda-streaming
        // wrapper (the framework module enforces it).
        invokeMode: "RESPONSE_STREAM",
      },
    });

    yield* server.bind`Allow(${server}, AWS.Website.Nextjs.Cache(${cacheBucket}))`({
      policyStatements: [
        {
          Effect: "Allow",
          Action: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
          Resource: [Output.interpolate`${cacheBucket.bucketArn}/*` as any],
        },
        {
          Effect: "Allow",
          Action: ["s3:ListBucket"],
          Resource: [cacheBucket.bucketArn as any],
        },
        {
          Effect: "Allow",
          Action: ["sqs:SendMessage"],
          Resource: [revalidationQueue.queueArn as any],
        },
        {
          Effect: "Allow",
          Action: [
            "dynamodb:GetItem",
            "dynamodb:PutItem",
            "dynamodb:DeleteItem",
            "dynamodb:Query",
            "dynamodb:Scan",
            "dynamodb:BatchGetItem",
            "dynamodb:BatchWriteItem",
            "dynamodb:UpdateItem",
          ],
          Resource: [
            tagCacheTable.tableArn as any,
            Output.interpolate`${tagCacheTable.tableArn}/index/*` as any,
          ],
        },
      ] satisfies PolicyStatement[],
    });

    // ISR revalidation consumer: drains the FIFO queue and HEAD-requests
    // stale pages with the prerender revalidate header.
    const revalidationFunction = yield* LambdaFunction("Revalidation", {
      main: fromDist("revalidation-function/index.mjs"),
      handler: "handler",
      isExternal: true,
      bundle: false,
      runtime: "nodejs24.x",
      memorySize: 512,
      timeout: Duration.seconds(30),
      functionUrl: false,
    });

    yield* revalidationFunction.bind`Allow(${revalidationFunction}, AWS.SQS.Consume(${revalidationQueue}))`(
      {
        policyStatements: [
          {
            Effect: "Allow",
            Action: [
              "sqs:ReceiveMessage",
              "sqs:DeleteMessage",
              "sqs:GetQueueAttributes",
              "sqs:GetQueueUrl",
              "sqs:ChangeMessageVisibility",
            ],
            Resource: [revalidationQueue.queueArn as any],
          },
        ] satisfies PolicyStatement[],
      },
    );

    yield* EventSourceMapping("RevalidationEventSource", {
      functionName: revalidationFunction.functionName,
      eventSourceArn: revalidationQueue.queueArn,
      batchSize: 5,
    });

    // Image optimization: OpenNext installs sharp's linux-arm64 binaries
    // into the bundle, so the function architecture is always arm64. Its
    // s3 image loader reads originals from the asset bucket.
    const imageFunction = yield* LambdaFunction("ImageOptimization", {
      main: fromDist("image-optimization-function/index.mjs"),
      handler: "handler",
      isExternal: true,
      bundle: false,
      runtime: "nodejs24.x",
      architecture: "arm64",
      memorySize: fnProps?.imageOptimization?.memorySize ?? 1536,
      timeout: Duration.seconds(25),
      env: {
        BUCKET_NAME: bucket.bucketName,
      },
      functionUrl: {
        authType: "NONE",
        // The image optimizer is buffered (streaming: false in the
        // OpenNext output manifest).
        invokeMode: "BUFFERED",
      },
    });

    yield* imageFunction.bind`Allow(${imageFunction}, AWS.S3.GetObject(${bucket}))`({
      policyStatements: [
        {
          Effect: "Allow",
          Action: ["s3:GetObject"],
          Resource: [Output.interpolate`${bucket.bucketArn}/*` as any],
        },
      ] satisfies PolicyStatement[],
    });

    const urlHost = (url: string | undefined) => {
      if (!url) {
        throw new Error("A Next.js Lambda function did not produce a Function URL.");
      }
      return new URL(url).hostname;
    };
    const serverHost = Output.map(urlHost)(server.functionUrl as any) as Input<string>;
    const imageHost = Output.map(urlHost)(imageFunction.functionUrl as any) as Input<string>;

    const siteProps: StaticSiteProps = {
      path: build.clientDir as unknown as string,
      assets: props.assets,
      domain: props.domain,
      cloudfrontUrl: props.cloudfrontUrl,
      edge: props.edge,
      bucketName: props.bucketName,
      forceDestroy: props.forceDestroy,
      invalidation: props.invalidation,
      tags: props.tags,
    };

    const site = yield* makeKvSite(id, siteProps, {
      serverHost,
      image: { route: "/_next/image", host: imageHost },
    });

    // Seed the ISR/fetch cache: `.open-next/cache/<buildId>/...` uploaded
    // under `_cache/` (matching CACHE_BUCKET_KEY_PREFIX). Old builds' seeds
    // are left in place so a rolling deploy never breaks in-flight ISR.
    const cacheFiles = yield* AssetDeployment("CacheFiles", {
      bucket: cacheBucket,
      sourcePath: fromDist("cache") as unknown as string,
      prefix: NEXTJS_CACHE_PREFIX,
      purge: false,
    });

    return {
      ...site,
      build,
      cacheBucket,
      cacheFiles,
      imageFunction,
      imageUrl: imageFunction.functionUrl,
      revalidationFunction,
      revalidationQueue,
      server,
      serverUrl: server.functionUrl,
      tagCacheTable,
    };
  },
  (effect, id: string, _props?: NextjsProps) => effect.pipe(Namespace.push(id)),
);