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

/**
 * `@alchemy.run/frontend-frameworks/astro/node` — the Node container deploy
 * target for the Astro integration.
 *
 * Astro's Node story is a plain Node SSR bundle behind a long-running HTTP
 * server: the adapter integration pins this package's `node-server`
 * entrypoint (which exports `App.render` as a fetch handler) as the build's
 * server entry, and forces the server build to be **self-contained**
 * (`vite.ssr.noExternal: true`). The finishing pass writes a Node HTTP
 * program that serves `clientDirectory` first, then falls through to that
 * handler on `PORT` (default 3000), and answers `GET /health`.
 *
 * - **`integration`** — the adapter integration: registers itself via
 *   `setAdapter` at `astro:config:done` (rejecting a user-declared adapter
 *   with an actionable error) and pins the `node-server` entrypoint.
 * - **`finish`** — a fully-static build (`output: "static"`) writes the
 *   same Node static serve entry Vite uses. Otherwise writes the HTTP
 *   serve entry (static files then the Astro fetch handler) and pins it
 *   as `serverModules[0]`.
 * - **`selectServerEntry`** — pins the adapter's entry chunk as
 *   `serverModules[0]` before the finishing pass wraps it.
 * - **`bundle`** — Node resolve conditions (no `workerd`, no `@aws-sdk/`).
 */
import type { AstroInlineConfig, AstroIntegration } from "astro";
import * as Effect from "effect/Effect";
import * as Path from "effect/Path";
import { runBuildChild } from "../core/BuildChild.ts";
import { DeployTargetError, makeDeployTarget, type ServerEntryChunk } from "../core/index.ts";
import {
  NODE_BUNDLE_CONDITIONS,
  NODE_SERVE_ENTRY_FILE_NAME,
  relativeClientDirExpression,
  writeNodeServeEntry,
  type NodeServeHtmlHandling,
  type NodeServeNotFoundHandling,
} from "../core/NodeServe.ts";
import { make } from "./Astro.ts";
import type { AstroTarget, AstroTargetBuildContext } from "./Target.ts";

/**
 * The importable specifier of this package's Node server entrypoint — the
 * module the adapter pins as `serverEntrypoint`. It exports a fetch
 * `handler`.
 */
export const SERVER_ENTRYPOINT = "@alchemy.run/frontend-frameworks/astro/entrypoints/node-server";

/** Node-specific target configuration. */
export interface AstroNodeConfig {
  readonly htmlHandling?: NodeServeHtmlHandling;
  readonly notFoundHandling?: NodeServeNotFoundHandling;
}

export interface AstroNodeTarget extends AstroTarget<AstroNodeConfig> {}

/** Options for {@link distilledNode} (the adapter integration). */
export interface DistilledNodeOptions {
  /**
   * 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.
   * @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]` before the serve wrap.
   * @internal
   */
  readonly onServerEntryName?: ((name: string) => void) | undefined;
}

/**
 * The Node 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 distilledNode = (options: DistilledNodeOptions = {}): AstroIntegration => {
  let injectedAdapterMarker = false;
  return {
    name: "@alchemy.run/frontend-frameworks/astro-node",
    hooks: {
      "astro:config:setup": ({ config, updateConfig }) => {
        if (config.adapter === undefined) {
          injectedAdapterMarker = true;
          updateConfig({
            adapter: {
              name: "@alchemy.run/frontend-frameworks/astro-node",
              hooks: {},
            },
          });
        }
      },
      "astro:config:done": ({ setAdapter, config, buildOutput }) => {
        if (config.adapter !== undefined && !injectedAdapterMarker) {
          throw new Error(
            `@alchemy.run/frontend-frameworks/astro/node: the Astro config declares the adapter "${config.adapter.name}", ` +
              "but the deploy target already provides the Node 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-node",
          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 Node server bundle; install it as a project dependency to optimize images at build time",
            },
          },
        });
      },
      "astro:build:setup": ({ vite: viteConfig, target }) => {
        if (target === "server") {
          viteConfig.ssr ||= {};
          viteConfig.ssr.noExternal = true;
        }
      },
    },
  };
};

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

const makeNodeAdapterTarget = (config: AstroNodeConfig = {}): AstroNodeTarget => {
  let buildOutput: "static" | "server" | undefined;
  let serverEntryName: string | undefined;
  return makeDeployTarget({
    platform: "node",
    config,
    bundle: {
      conditions: [...NODE_BUNDLE_CONDITIONS],
    },
    integration: () =>
      distilledNode({
        onBuildOutput: (mode) => {
          buildOutput = mode;
        },
        onServerEntryName: (name) => {
          serverEntryName = name;
        },
      }),
    selectServerEntry: (chunk: ServerEntryChunk): boolean =>
      chunk.fileName === (serverEntryName ?? "entry.mjs") ||
      (chunk.facadeModuleId !== null &&
        /\/entrypoints\/node-server\.(?:ts|js|mjs)$/.test(
          chunk.facadeModuleId.replaceAll("\\", "/"),
        )),
    finish: (output) =>
      Effect.gen(function* () {
        const path = yield* Path.Path;
        if (buildOutput === "static") {
          if (output.clientDirectory === undefined) {
            return yield* fail(
              "The Astro static build produced no client directory for the Node serve entry",
            );
          }
          const servePath = path.join(output.clientDirectory, NODE_SERVE_ENTRY_FILE_NAME);
          return yield* writeNodeServeEntry({
            output: { ...output, distDirectory: output.clientDirectory },
            servePath,
            serveModuleName: NODE_SERVE_ENTRY_FILE_NAME,
            clientDirExpression: `fileURLToPath(new URL("./", import.meta.url))`,
            notFoundHandling: config.notFoundHandling ?? "spa",
            htmlHandling: config.htmlHandling,
            platform: "node",
          });
        }
        if (output.distDirectory === undefined || output.clientDirectory === undefined) {
          return yield* fail(
            "The Astro build produced no dist/client directories for the Node serve entry",
          );
        }
        const entryName = serverEntryName ?? "entry.mjs";
        const servePath = path.join(output.distDirectory, "server", NODE_SERVE_ENTRY_FILE_NAME);
        return yield* writeNodeServeEntry({
          output,
          servePath,
          serveModuleName: path.join("server", NODE_SERVE_ENTRY_FILE_NAME).replaceAll("\\", "/"),
          clientDirExpression: relativeClientDirExpression(servePath, output.clientDirectory),
          handler: {
            kind: "fetch",
            imports: `import { handler } from ${JSON.stringify(`./${entryName}`)};`,
            expr: "handler",
          },
          notFoundHandling: config.notFoundHandling,
          htmlHandling: config.htmlHandling,
          platform: "node",
        });
      }),
  });
};

export interface AstroNodeBuildChildConfig {
  readonly rootDir: string;
  readonly config: AstroNodeConfig;
  readonly astro: AstroInlineConfig | undefined;
}

export const buildInChild = (config: AstroNodeBuildChildConfig) =>
  Effect.gen(function* () {
    const framework = yield* make({
      root: config.rootDir,
      target: makeNodeAdapterTarget(config.config),
      astro: config.astro,
    });
    return yield* framework.build({ root: config.rootDir });
  });

/**
 * Build the Node {@link AstroTarget}. See the module doc for the seams.
 */
export const makeNodeTarget = (config: AstroNodeConfig = {}): AstroNodeTarget => ({
  ...makeNodeAdapterTarget(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 AstroNodeBuildChildConfig,
    }).pipe(Effect.mapError((error) => fail(error.message, error.cause))),
});

export const target = makeNodeTarget;

export default makeNodeTarget;