sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ nextjs/ standalone.ts

/**
 * Next.js on an AWS Lambda Web Function: Next's own standalone server, no
 * OpenNext.
 *
 * A Web Function is a long-lived Node server, so Next runs the way it does
 * under `next start`: SSR, middleware, ISR background revalidation and
 * `/_next/image` all happen in-process. The build:
 *
 * 1. runs the project's `next build` with `NEXT_PRIVATE_STANDALONE` set, so
 *    Next traces a self-contained server directory without a change to
 *    `next.config.*`
 * 2. copies the S3 `cacheHandler` (`./cache-handler.ts`) into it, so every
 *    environment shares one ISR, fetch and image cache
 * 3. installs `sharp` for Linux on Arm64, which Next's image optimizer needs
 * 4. writes `serve-node.mjs`, which starts Next's server (as the generated
 *    `server.js` does) with the cache handler, listening on
 *    `AWS_LAMBDA_HTTP_ENDPOINT`
 * 5. copies `public/` and `.next/static` into the server (the image
 *    optimizer reads local images from it) and gathers them for S3
 */
import { createRequire } from "node:module";
import { fileURLToPath } from "node:url";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import * as ChildProcess from "effect/process/ChildProcess";
import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as Stream from "effect/Stream";
import { logChildOutput } from "../core/ChildOutput.ts";
import * as FrameworkCore from "../core/index.ts";

const fail = (message: string) => (cause: unknown) =>
  new FrameworkCore.FrameworkError({ framework: "nextjs", message, cause });

/** The entry the Web Function starts, inside the standalone app directory. */
export const STANDALONE_SERVE_ENTRY_FILE_NAME = "serve-node.mjs";

/** The S3 cache handler's file name inside the standalone app directory. */
export const STANDALONE_CACHE_HANDLER_FILE_NAME = "alchemy-cache-handler.mjs";

/** The directory of files uploaded to S3, under `.next`. */
export const STANDALONE_ASSETS_DIRECTORY = "alchemy-assets";

/**
 * Start Next's standalone server the way its generated `server.js` does,
 * with the S3 cache handler and the address Lambda passes in
 * `AWS_LAMBDA_HTTP_ENDPOINT`.
 */
export const makeStandaloneServeEntrySource = (
  nextConfig: Record<string, unknown>,
  buildTime: number,
) => `// Generated by @alchemy.run/frontend-frameworks/nextjs/aws — do not edit.
import { createRequire } from "node:module";
import * as path from "node:path";
import { fileURLToPath } from "node:url";

const require = createRequire(import.meta.url);
const dir = path.dirname(fileURLToPath(import.meta.url));

process.env.NODE_ENV = "production";
// The archive's file times are normalized, so prerendered pages are dated
// by the build instead (see the cache handler).
process.env.ALCHEMY_NEXT_BUILD_TIME = "${buildTime}";
process.chdir(dir);

const endpoint = process.env.AWS_LAMBDA_HTTP_ENDPOINT ?? "127.0.0.1:3000";
const separator = endpoint.lastIndexOf(":");
const hostname = endpoint.slice(0, separator).replace(/^\\[(.*)\\]$/, "$1");
const port = Number.parseInt(endpoint.slice(separator + 1), 10);

const nextConfig = {
  ...${JSON.stringify(nextConfig)},
  cacheHandler: path.join(dir, ${JSON.stringify(STANDALONE_CACHE_HANDLER_FILE_NAME)}),
};
process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig);

require("next");
const { startServer } = require("next/dist/server/lib/start-server");

await startServer({
  dir,
  isDev: false,
  config: nextConfig,
  hostname,
  port,
  allowRetry: false,
});
`;

/** Run a command to completion, forwarding its output. */
const run = (cmd: string, args: ReadonlyArray<string>, cwd: string, env: Record<string, string>) =>
  Effect.scoped(
    Effect.gen(function* () {
      const child = yield* ChildProcess.make(cmd, [...args], {
        cwd,
        stdin: "ignore",
        stdout: "pipe",
        stderr: "pipe",
        env,
      }).pipe(Effect.mapError(fail(`Failed to spawn ${cmd} (is it on PATH?)`)));
      // Build output becomes log records, so the process that renders logs
      // shows it and in-process capture (a test runner's log file) sees it.
      const forward = (
        stream: Stream.Stream<Uint8Array, PlatformError>,
        name: "stdout" | "stderr",
      ) =>
        stream.pipe(
          Stream.decodeText,
          Stream.splitLines,
          Stream.runForEach((line) => logChildOutput(line, name)),
        );
      const { exitCode } = yield* Effect.all(
        {
          exitCode: child.exitCode,
          stdout: forward(child.stdout, "stdout"),
          stderr: forward(child.stderr, "stderr"),
        },
        { concurrency: "unbounded" },
      ).pipe(Effect.mapError(fail(`Failed reading the output of ${cmd} ${args.join(" ")}`)));
      if (exitCode !== 0) {
        return yield* fail(`${cmd} ${args.join(" ")} exited with code ${exitCode}`)(undefined);
      }
    }),
  );

const resolveCacheHandlerPath = Effect.try({
  try: () =>
    fileURLToPath(import.meta.resolve("@alchemy.run/frontend-frameworks/nextjs/cache-handler")),
  catch: fail(
    'Failed to resolve "@alchemy.run/frontend-frameworks/nextjs/cache-handler" — is the package built?',
  ),
});

/** The version of `sharp` the project resolves, if any. */
const projectSharpVersion = (root: string) =>
  Effect.sync(() => {
    try {
      const require = createRequire(`${root.replace(/\/+$/, "")}/package.json`);
      const packageJson = require.resolve("sharp/package.json");
      return (require(packageJson) as { version: string }).version;
    } catch {
      return undefined;
    }
  });

/** Copy a directory's contents into another, if it exists. */
const copyInto = (from: string, to: string) =>
  Effect.gen(function* () {
    const fs = yield* FileSystem.FileSystem;
    if (!(yield* fs.exists(from).pipe(Effect.orElseSucceed(() => false)))) return;
    yield* fs.makeDirectory(to, { recursive: true });
    yield* fs.copy(from, to, { overwrite: true });
  });

export const buildStandalone = Effect.fn(function* (options: {
  readonly root: string;
  readonly cli: string;
  readonly env: Record<string, string> | undefined;
}) {
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const { root } = options;

  const env = yield* Effect.sync(() => ({
    ...(process.env as Record<string, string>),
    ...options.env,
    NODE_ENV: "production",
    // Next's switch for `output: "standalone"` when the config sets none.
    NEXT_PRIVATE_STANDALONE: "true",
  }));
  yield* run("node", [options.cli, "build"], root, env);
  const buildTime = yield* Effect.sync(() => Date.now());

  const nextDir = path.join(root, ".next");
  const serverFilesPath = path.join(nextDir, "required-server-files.json");
  const serverFiles = yield* fs.readFileString(serverFilesPath).pipe(
    Effect.flatMap((raw) =>
      Effect.try({
        try: () =>
          JSON.parse(raw) as {
            config: Record<string, unknown> & { output?: string };
            relativeAppDir?: string;
          },
        catch: fail(`Failed to parse ${serverFilesPath}`),
      }),
    ),
    Effect.mapError(fail(`The next build produced no ${serverFilesPath}`)),
  );
  if (serverFiles.config.output !== "standalone") {
    return yield* fail(
      `next.config sets output: "${serverFiles.config.output}". A Lambda Web Function runs Next's standalone server; remove output, or set it to "standalone".`,
    )(undefined);
  }
  // In a monorepo Next traces from the workspace root, so the app sits
  // below `.next/standalone` at its path relative to that root.
  const appDir = path.join(nextDir, "standalone", serverFiles.relativeAppDir ?? "");
  if (!(yield* fs.exists(path.join(appDir, "server.js")).pipe(Effect.orElseSucceed(() => false)))) {
    return yield* fail(`The next build produced no standalone server in ${appDir}`)(undefined);
  }

  yield* fs
    .copyFile(yield* resolveCacheHandlerPath, path.join(appDir, STANDALONE_CACHE_HANDLER_FILE_NAME))
    .pipe(Effect.mapError(fail("Failed to copy the S3 cache handler")));

  // Next's image optimizer needs sharp built for the function's platform.
  // Install it in an empty project (the standalone directory carries the
  // app's package.json, which npm would try to resolve whole), then merge
  // its node_modules into the server's.
  const sharpVersion = yield* projectSharpVersion(root);
  const sharpProject = yield* fs
    .makeTempDirectory({ prefix: "alchemy-next-sharp-" })
    .pipe(Effect.mapError(fail("Failed to create a directory for sharp")));
  yield* fs
    .writeFileString(
      path.join(sharpProject, "package.json"),
      JSON.stringify({ name: "alchemy-next-sharp", private: true }),
    )
    .pipe(Effect.mapError(fail("Failed to prepare the sharp install")));
  yield* run(
    "npm",
    [
      "install",
      "--no-package-lock",
      "--no-audit",
      "--no-fund",
      "--os=linux",
      "--cpu=arm64",
      "--libc=glibc",
      `sharp${sharpVersion ? `@${sharpVersion}` : ""}`,
    ],
    sharpProject,
    env,
  );
  yield* copyInto(path.join(sharpProject, "node_modules"), path.join(appDir, "node_modules")).pipe(
    Effect.mapError(fail("Failed to add sharp to the standalone server")),
  );
  yield* fs.remove(sharpProject, { recursive: true }).pipe(Effect.ignore);

  yield* fs
    .writeFileString(
      path.join(appDir, STANDALONE_SERVE_ENTRY_FILE_NAME),
      makeStandaloneServeEntrySource(serverFiles.config, buildTime),
    )
    .pipe(Effect.mapError(fail("Failed to write the Web Function entry")));

  // Next's image optimizer loads local images (`public/`, and static
  // imports under `/_next/static/media`) from its own server, which only has
  // them when they are copied in, as Next's standalone docs describe.
  yield* copyInto(path.join(root, "public"), path.join(appDir, "public")).pipe(
    Effect.mapError(fail("Failed to copy public/ into the standalone server")),
  );
  yield* copyInto(path.join(nextDir, "static"), path.join(appDir, ".next", "static")).pipe(
    Effect.mapError(fail("Failed to copy .next/static into the standalone server")),
  );

  // S3 serves `public/` at the root and the build's hashed files under
  // `/_next/static`.
  const assets = path.join(nextDir, STANDALONE_ASSETS_DIRECTORY);
  yield* fs.remove(assets, { recursive: true }).pipe(Effect.ignore);
  yield* copyInto(path.join(root, "public"), assets).pipe(
    Effect.mapError(fail("Failed to gather public/ for upload")),
  );
  yield* copyInto(path.join(nextDir, "static"), path.join(assets, "_next", "static")).pipe(
    Effect.mapError(fail("Failed to gather .next/static for upload")),
  );

  return {
    distDirectory: nextDir,
    clientDirectory: assets,
    serverModules: [
      { name: path.relative(nextDir, path.join(appDir, STANDALONE_SERVE_ENTRY_FILE_NAME)) },
    ],
  };
});

export type StandaloneBuildRequirements =
  | FileSystem.FileSystem
  | Path.Path
  | ChildProcessSpawner.ChildProcessSpawner;