sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ astro/ aws.ts

/**
 * `@alchemy.run/frontend-frameworks/astro/aws` — the AWS Lambda deploy target
 * for the Astro integration.
 *
 * Astro's AWS story is a plain Node SSR bundle behind a Lambda Function
 * URL: the adapter integration pins this package's `aws-server` entrypoint
 * (which wraps `App.render` with the `@alchemy.run/frontend-frameworks/aws-lambda`
 * handler adapter) as the build's server entry, and forces the server build
 * to be **self-contained** (`vite.ssr.noExternal: true`) so `dist/server`
 * can ship to Lambda as-is (`bundle: false`). What this target owns:
 *
 * - **`integration`** — the adapter integration: registers itself via
 *   `setAdapter` at `astro:config:done` (rejecting a user-declared adapter
 *   with an actionable error), pins the `aws-server` entrypoint, and
 *   configures the server build for self-containment.
 * - **`finish`** — a fully-static build (`output: "static"`: every route
 *   prerendered) deploys ASSETS-ONLY: `serverModules` is dropped so the
 *   composite skips the Lambda entirely.
 * - **`selectServerEntry`** — pins the adapter's entry chunk as
 *   `serverModules[0]` (astro's page modules are rolldown inputs in the
 *   same environment, so the entry environment emits many entry chunks).
 * - **`bundle`** — Node resolve conditions and the `@aws-sdk/` externals
 *   (the Lambda Node.js runtime ships SDK v3) for callers that post-process
 *   server code.
 *
 * No `devPlatform`: `dev` runs Astro's own Node dev server, which is
 * already the AWS Lambda programming model (plain Node).
 */
import type { AstroInlineConfig, AstroIntegration } from "astro";
import * as Effect from "effect/Effect";
import { runBuildChild } from "../core/BuildChild.ts";
import { DeployTargetError, makeDeployTarget, type ServerEntryChunk } from "../core/index.ts";
import { make } from "./Astro.ts";
import type { AstroTarget, AstroTargetBuildContext } from "./Target.ts";

/**
 * The importable specifier of this package's AWS Lambda server entrypoint —
 * the module the adapter pins as `serverEntrypoint`. It exports the Lambda
 * `handler` (streaming by default).
 */
export const SERVER_ENTRYPOINT = "@alchemy.run/frontend-frameworks/astro/entrypoints/aws-server";

/** AWS-specific target configuration. */
export interface AstroAwsConfig {
  /**
   * Whether the emitted Lambda handler streams its response
   * (`awslambda.streamifyResponse`, requires a Function URL with
   * `invokeMode: RESPONSE_STREAM`). With `false` — or whenever the
   * `awslambda` global is absent — the buffered handler answers
   * APIGW/Function-URL events with a complete payload-v2 response object.
   * @default true
   */
  readonly streaming?: boolean | undefined;
}

export interface AstroAwsTarget extends AstroTarget<AstroAwsConfig> {}

/** Options for {@link distilledAws} (the adapter integration). */
export interface DistilledAwsOptions {
  /** See {@link AstroAwsConfig.streaming}. @default true */
  readonly streaming?: boolean | undefined;
  /**
   * Reports the resolved build output mode (`astro:config:done`'s
   * `buildOutput`): `"static"` when every route is prerendered, `"server"`
   * when any route renders on demand. The target's `finish` pass uses it to
   * strip `serverModules` from a fully-static build so the deploy is
   * assets-only (no Lambda).
   * @internal
   */
  readonly onBuildOutput?: ((buildOutput: "static" | "server") => void) | undefined;
  /**
   * Reports the resolved server-entry file name (`config.build.serverEntry`,
   * `entry.mjs` by default) so the entry chunk can be pinned as
   * `serverModules[0]`.
   * @internal
   */
  readonly onServerEntryName?: ((name: string) => void) | undefined;
}

/**
 * The AWS Lambda adapter integration for Astro. Injected via
 * `integrations` (after the user's) rather than `adapter`: it registers
 * itself as the adapter at `astro:config:done`, where it also rejects a
 * user-declared adapter with an actionable error.
 */
export const distilledAws = (options: DistilledAwsOptions = {}): AstroIntegration => {
  // Whether WE satisfied `config.adapter`. The user's astro.config.* loads
  // natively and this integration is injected via `integrations`, but
  // astro's build refuses server output unless `config.adapter` is set — so
  // `astro:config:setup` injects a hookless marker when the config declares
  // no adapter (the real adapter registration is `setAdapter` at
  // `astro:config:done`). When the flag is still false at
  // `astro:config:done`, the user declared their own adapter — a conflict.
  let injectedAdapterMarker = false;
  return {
    name: "@alchemy.run/frontend-frameworks/astro-aws",
    hooks: {
      "astro:config:setup": ({ config, updateConfig }) => {
        if (config.adapter === undefined) {
          injectedAdapterMarker = true;
          updateConfig({
            adapter: {
              name: "@alchemy.run/frontend-frameworks/astro-aws",
              hooks: {},
            },
          });
        }
      },
      "astro:config:done": ({ setAdapter, config, buildOutput }) => {
        if (config.adapter !== undefined && !injectedAdapterMarker) {
          throw new Error(
            `@alchemy.run/frontend-frameworks/astro/aws: the Astro config declares the adapter "${config.adapter.name}", ` +
              "but the deploy target already provides the AWS Lambda adapter. " +
              "Remove `adapter` from your astro.config file — user integrations " +
              "(react, mdx, tailwind, ...) are honored, and the adapter is injected by the toolchain.",
          );
        }
        options.onBuildOutput?.(buildOutput);
        options.onServerEntryName?.(config.build.serverEntry);
        setAdapter({
          name: "@alchemy.run/frontend-frameworks/astro-aws",
          entrypointResolution: "auto",
          serverEntrypoint: SERVER_ENTRYPOINT,
          adapterFeatures: {
            buildOutput,
            middlewareMode: "classic",
            preserveBuildClientDir: true,
            preserveBuildServerDir: true,
          },
          supportedAstroFeatures: {
            serverOutput: "stable",
            hybridOutput: "stable",
            staticOutput: "stable",
            i18nDomains: "experimental",
            envGetSecret: "stable",
            sharpImageService: {
              support: "limited",
              message:
                "sharp is not shipped with the Lambda server bundle; install it as a project dependency to optimize images at build time",
            },
          },
        });
      },
      "astro:build:setup": ({ vite: viteConfig, target }) => {
        if (target === "server") {
          // Self-contained dist/server: Lambda ships the directory as-is
          // (`bundle: false`), so every server dependency must be bundled
          // into the emitted chunks. Node builtins stay external
          // automatically; sharp is a native module that can never bundle,
          // and the Lambda Node.js runtime provides `@aws-sdk/*` v3.
          viteConfig.ssr ||= {};
          viteConfig.ssr.noExternal = true;
          viteConfig.build ||= {};
          const build = viteConfig.build as Record<string, any>;
          build.rolldownOptions ||= {};
          build.rolldownOptions.external = ["sharp", /^@aws-sdk\//];
          viteConfig.define = {
            __ALCHEMY_ASTRO_AWS_STREAMING__: JSON.stringify(options.streaming ?? true),
            ...viteConfig.define,
          };
        }
      },
    },
  };
};

const fail = (message: string, cause?: unknown) =>
  new DeployTargetError({ platform: "aws", message, cause });

/**
 * The adapter-driven target — the shape the framework's regular
 * build/finish pipeline consumes. Used directly in the build child (where
 * `cwd === root` holds); {@link target} wraps it with the wholesale
 * `build` hook that spawns the child.
 */
const makeAwsAdapterTarget = (config: AstroAwsConfig = {}): AstroAwsTarget => {
  // The resolved build output mode from `astro:config:done`: `"static"`
  // means every route is prerendered, so the deploy must be assets-only.
  let buildOutput: "static" | "server" | undefined;
  // The resolved server-entry file name (`entry.mjs` by default).
  let serverEntryName: string | undefined;
  return makeDeployTarget({
    platform: "aws",
    config,
    bundle: {
      conditions: ["node", "import", "module"],
      external: ["@aws-sdk/"],
    },
    integration: () =>
      distilledAws({
        streaming: config.streaming,
        onBuildOutput: (mode) => {
          buildOutput = mode;
        },
        onServerEntryName: (name) => {
          serverEntryName = name;
        },
      }),
    // Astro's page modules are rolldown inputs of the `ssr` environment, so
    // it emits many entry chunks; pin the adapter's server entry (renamed to
    // `config.build.serverEntry` by astro, facade = the aws-server module).
    selectServerEntry: (chunk: ServerEntryChunk): boolean =>
      chunk.fileName === (serverEntryName ?? "entry.mjs") ||
      (chunk.facadeModuleId !== null &&
        /\/entrypoints\/aws-server\.(?:ts|js|mjs)$/.test(
          chunk.facadeModuleId.replaceAll("\\", "/"),
        )),
    // A fully-static build deploys ASSETS-ONLY: the SSR entry astro bundled
    // for prerendering is dropped from the output and the client directory
    // carries all prerendered HTML, `404.html` included.
    finish: (output) =>
      Effect.succeed(buildOutput === "static" ? { ...output, serverModules: undefined } : output),
  });
};

/**
 * The natively-loaded `astro.config.*` executes user plugins/integrations
 * that may read the cwd, mutate `process.env`, or `process.chdir` — none of
 * which may touch the engine process (many deploys share one event loop).
 * This target's wholesale `build` therefore runs the framework in a
 * disposable child process whose working directory IS the project root (see
 * `core/BuildChild.ts`). The shared `core/BuildChildRunner` entry imports
 * this module in the child and calls the exported {@link buildInChild}.
 */
export interface AstroAwsBuildChildConfig {
  readonly rootDir: string;
  /** The (JSON-serializable) target config the parent was created with. */
  readonly config: AstroAwsConfig;
  /**
   * The inline Astro overlay the framework was constructed with
   * (`AstroFrameworkOptions.astro`, carried through the build context).
   * Only JSON-serializable fields cross the process boundary.
   */
  readonly astro: AstroInlineConfig | undefined;
}

export const buildInChild = (config: AstroAwsBuildChildConfig) =>
  Effect.gen(function* () {
    const framework = yield* make({
      root: config.rootDir,
      // The adapter-only target: no wholesale `build` hook, so the child
      // runs the regular astro build + finish pipeline (no recursion).
      target: makeAwsAdapterTarget(config.config),
      astro: config.astro,
    });
    return yield* framework.build({ root: config.rootDir });
  });

/**
 * Build the AWS Lambda {@link AstroTarget}. See the module doc for the
 * seams.
 */
export const target = (config: AstroAwsConfig = {}): AstroAwsTarget => ({
  ...makeAwsAdapterTarget(config),
  build: (context: AstroTargetBuildContext) =>
    runBuildChild({
      module: import.meta.url,
      rootDir: context.root,
      env: context.env,
      framework: "astro",
      config: {
        rootDir: context.root,
        config,
        astro: context.astro,
      } satisfies AstroAwsBuildChildConfig,
    }).pipe(Effect.mapError((error) => fail(error.message, error.cause))),
});

/**
 * The deploy-target module contract (`resolveDeployTarget` accepts the
 * default export — or the named `target` export — as a value or factory).
 */
export default target;