import type * as NodeChildProcessModule from "node:child_process";
import { createRequire } from "node:module";
import type * as NodeNet from "node:net";
import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import * as ChildProcess from "effect/process/ChildProcess";
import * as Schema from "effect/Schema";
import type * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import { runBuildChild } from "../core/BuildChild.ts";
import { makeChildOutput } from "../core/ChildOutput.ts";
import { logChildOutput } from "../core/ChildOutput.ts";
/**
* `@alchemy.run/frontend-frameworks/nextjs/node` — Next.js on a Node
* container (`next build` + a custom `next({ dev: false })` server).
*
* Unlike the Cloudflare (`./index.ts`, OpenNext CF) and AWS (`./aws.ts`,
* OpenNext AWS) integrations, this module does **not** use OpenNext. The
* container-optimal path is a long-running Node process:
*
* - **`build`** runs the project's `next build` in a disposable child
* (cwd = project root), then writes the shared Node serve entry
* (`GET /health`, listens on `PORT`, default 3000) around
* {@link NEXT_PRODUCTION_APP_SOURCE}: `next({ dev: false }).prepare()`
* over the resolved build config + `getRequestHandler()`.
* - **`dev`** runs the real `next dev` CLI (plain Node), scoped.
*
* Composites should load this module as the framework specifier (same
* shape as `./aws`) or pass `target:
* "@alchemy.run/frontend-frameworks/nextjs/node"`.
*/
import * as FrameworkCore from "../core/index.ts";
import { DeployTargetError, makeDeployTarget, type DeployTarget } from "../core/index.ts";
import {
NODE_BUNDLE_CONDITIONS,
NODE_SERVE_ENTRY_FILE_NAME,
writeNodeServeEntry,
type NodeServeHandler,
} from "../core/NodeServe.ts";
const failFramework = (message: string) => (cause: unknown) =>
new FrameworkCore.FrameworkError({ framework: "nextjs", message, cause });
const failTarget = (message: string, cause?: unknown) =>
new DeployTargetError({ platform: "node", message, cause });
/** Options for the Next.js Node framework module / deploy target. */
export interface NextjsNodeOptions {
readonly root?: string | undefined;
/**
* The deploy target module specifier the caller resolved this module as.
* This module IS the Node target — accepted and ignored (parity with
* `./aws`).
*/
readonly target?: string | undefined;
}
export interface NextjsNodeTargetConfig {
readonly root?: string | undefined;
}
export interface NextjsNodeTarget extends DeployTarget<NextjsNodeTargetConfig> {}
/** Serve-entry module name relative to the project root. */
export const SERVER_ENTRY_NAME = NODE_SERVE_ENTRY_FILE_NAME;
/**
* Serve-entry statements that start Next in production mode as `app`.
* Mirrors Next's standalone `server.js`: the resolved build config from
* `.next/required-server-files.json` is handed over via
* `__NEXT_PRIVATE_STANDALONE_CONFIG`, so Next never reloads
* `next.config.*` at runtime (which would recompile TypeScript configs
* and download SWC into a possibly read-only bundle). Expects `fs`,
* `path` and `fileURLToPath` in scope (both serve templates import them).
*/
export const NEXT_PRODUCTION_APP_SOURCE = [
'import next from "next";',
"const dir = path.dirname(fileURLToPath(import.meta.url));",
'process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(JSON.parse(fs.readFileSync(path.join(dir, ".next", "required-server-files.json"), "utf8")).config);',
"const app = next({ dev: false, dir });",
"await app.prepare();",
].join("\n");
/** The production Next request listener for the shared Node serve entry. */
export const nextNodeServeHandler: NodeServeHandler = {
kind: "node",
imports: `${NEXT_PRODUCTION_APP_SOURCE}\nconst nextHandler = app.getRequestHandler();`,
expr: "nextHandler",
};
const resolveNextCli = (root: string) =>
Effect.try({
try: () => {
const require = createRequire(`${root.replace(/\/+$/, "")}/package.json`);
return require.resolve("next/dist/bin/next");
},
catch: failFramework(
`Failed to resolve "next" from ${root}. ` + "It must be installed in your project.",
),
});
const runNextBuild = (options: { readonly root: string; readonly cli: string }) =>
Effect.scoped(
Effect.gen(function* () {
const env = yield* Effect.sync(() => ({ ...process.env, NODE_ENV: "production" }));
const child = yield* ChildProcess.make("node", [options.cli, "build"], {
cwd: options.root,
stdin: "ignore",
stdout: "pipe",
stderr: "pipe",
env,
}).pipe(
Effect.mapError(failFramework("Failed to spawn the next build CLI (is `node` 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(failFramework("Failed reading next build output")));
if (exitCode !== 0) {
return yield* failFramework(`The next build exited with code ${exitCode}`)(undefined);
}
}),
);
/** The slice of `.next/required-server-files.json` the build inspects. */
const RequiredServerFiles = Schema.Struct({
config: Schema.Struct({ output: Schema.optional(Schema.String) }),
});
const collectNextOutput = (root: string) =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const nextDir = path.join(root, ".next");
const hasNext = yield* fs.exists(nextDir).pipe(Effect.orElseSucceed(() => false));
if (!hasNext) {
return yield* failFramework(`The next build produced no ${nextDir}`)(undefined);
}
const serverFilesPath = path.join(nextDir, "required-server-files.json");
const { config } = yield* fs
.readFileString(serverFilesPath)
.pipe(
Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(RequiredServerFiles))),
Effect.mapError(failFramework(`Failed to read the built Next config ${serverFilesPath}`)),
);
if (config.output === "export") {
return yield* failFramework(
'`output: "export"` builds a static site with no Next server, so it ' +
'cannot run on the Node target. Remove `output: "export"` from ' +
"next.config, or deploy the exported `out/` directory as a static site.",
)(undefined);
}
const publicDir = path.join(root, "public");
const hasPublic = yield* fs.exists(publicDir).pipe(Effect.orElseSucceed(() => false));
// No `clientDirExpression`: Next serves `.next/static` and `public/`
// itself from the serve entry's `dir` (the project root).
return yield* writeNodeServeEntry({
output: {
distDirectory: root,
clientDirectory: hasPublic ? root : nextDir,
serverModules: [],
externalWorkspaces: new Set<string>(),
},
servePath: path.join(root, SERVER_ENTRY_NAME),
serveModuleName: SERVER_ENTRY_NAME,
handler: nextNodeServeHandler,
}).pipe(Effect.mapError((error) => failFramework(error.message)(error.cause)));
});
export interface NextjsNodeBuildChildConfig {
readonly rootDir: string;
readonly config: NextjsNodeTargetConfig;
}
export const buildInChild = (config: NextjsNodeBuildChildConfig) =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const root = config.rootDir;
const cli = yield* resolveNextCli(root);
const spawnerLayer = NodeChildProcessSpawner.layer.pipe(
Layer.provide(
Layer.merge(Layer.succeed(FileSystem.FileSystem)(fs), Layer.succeed(Path.Path)(path)),
),
);
yield* runNextBuild({ root, cli }).pipe(Effect.provide(spawnerLayer));
return yield* collectNextOutput(root);
});
const makeNodeChildTarget = (config: NextjsNodeTargetConfig = {}): NextjsNodeTarget =>
makeDeployTarget({
platform: "node",
config,
bundle: { conditions: [...NODE_BUNDLE_CONDITIONS] },
});
/**
* Create the Node {@link NextjsNodeTarget}: wholesale `next build` in a
* child process, then a custom-server serve entry.
*/
export const makeNodeTarget = (config: NextjsNodeTargetConfig = {}): NextjsNodeTarget => ({
...makeNodeChildTarget(config),
build: (context) =>
runBuildChild({
module: import.meta.url,
rootDir: context.root,
env: context.env,
framework: "nextjs",
config: { rootDir: context.root, config } satisfies NextjsNodeBuildChildConfig,
}).pipe(Effect.mapError((error) => failTarget(error.message, error.cause))),
});
export const target = makeNodeTarget;
export default makeNodeTarget;
// ---------------------------------------------------------------------------
// Framework-module contract (AWS.Website.Server / container composites)
// ---------------------------------------------------------------------------
const pickEphemeralPort: Effect.Effect<number, FrameworkCore.FrameworkError> = Effect.callback(
(resume) => {
const net = createRequire(import.meta.url)("net") as typeof NodeNet;
const server = net.createServer();
server.once("error", (cause) =>
resume(Effect.fail(failFramework("Failed to allocate an ephemeral port")(cause))),
);
server.listen(0, "127.0.0.1", () => {
const address = server.address();
if (address === null || typeof address === "string") {
server.close();
resume(Effect.fail(failFramework("No TCP address for the port probe")(null)));
return;
}
const port = address.port;
server.close(() => resume(Effect.succeed(port)));
});
},
);
interface NextDevChild {
readonly exited: () => boolean;
readonly output: () => string;
}
const spawnNextDev = (options: {
readonly root: string;
readonly cli: string;
readonly port: number;
readonly host?: string | undefined;
}): Effect.Effect<NextDevChild, FrameworkCore.FrameworkError, Scope.Scope> =>
Effect.acquireRelease(
Effect.flatMap(makeChildOutput, (childOutput) =>
Effect.try({
try: () => {
const cp = createRequire(import.meta.url)(
"child_process",
) as typeof NodeChildProcessModule;
const child = cp.spawn(
"node",
[
options.cli,
"dev",
"-p",
String(options.port),
...(options.host !== undefined ? ["-H", options.host] : []),
],
{ cwd: options.root, stdio: ["ignore", "pipe", "pipe"], detached: false },
);
let exited = false;
let output = "";
const capture = (chunk: unknown) => {
output += String(chunk);
if (output.length > 65536) output = output.slice(-32768);
};
child.stdout?.on("data", (chunk: unknown) => {
capture(chunk);
childOutput.stdout.push(String(chunk));
});
child.stderr?.on("data", (chunk: unknown) => {
capture(chunk);
childOutput.stderr.push(String(chunk));
});
// Output without a trailing newline is still a line once the
// streams close.
child.once("close", () => {
childOutput.stdout.flush();
childOutput.stderr.flush();
});
child.once("exit", () => {
exited = true;
});
return {
child,
handle: { exited: () => exited, output: () => output } satisfies NextDevChild,
};
},
catch: failFramework("Failed to spawn the next dev CLI (is `node` on PATH?)"),
}),
),
({ child }) =>
Effect.callback<void>((resume) => {
if (child.exitCode !== null) {
resume(Effect.void);
return;
}
const killTimer = setTimeout(() => child.kill("SIGKILL"), 3000);
child.once("exit", () => {
clearTimeout(killTimer);
resume(Effect.void);
});
child.kill("SIGTERM");
}),
).pipe(Effect.map(({ handle }) => handle));
/**
* Poll until the allocated port accepts a TCP connection. Next 16 prints
* Ready and binds before loading next.config / compiling App Router, so a
* GET / probe with a 2s abort restarts the first compile and never
* converges.
*/
const awaitNextDevReady = (options: {
readonly url: string;
readonly child: NextDevChild;
}): Effect.Effect<void, FrameworkCore.FrameworkError> =>
Effect.gen(function* () {
const parsed = yield* Effect.try({
try: () => new URL(options.url),
catch: failFramework(`Invalid next dev URL: ${options.url}`),
});
const port = Number(parsed.port);
const hostname = parsed.hostname;
for (let attempt = 0; attempt < 240; attempt++) {
if (options.child.exited()) {
return yield* failFramework(
`The next dev CLI exited before becoming ready:\n${options.child.output().slice(-4000)}`,
)(undefined);
}
const ready = yield* Effect.callback<boolean>((resume) => {
const net = createRequire(import.meta.url)("net") as typeof NodeNet;
let settled = false;
const finish = (value: boolean) => {
if (settled) return;
settled = true;
resume(Effect.succeed(value));
};
const socket = net.connect({ host: hostname, port }, () => {
socket.destroy();
finish(true);
});
socket.setTimeout(2000, () => {
socket.destroy();
finish(false);
});
socket.once("error", () => {
socket.destroy();
finish(false);
});
return Effect.sync(() => {
settled = true;
socket.destroy();
});
});
if (ready) return;
yield* Effect.sleep(500);
}
return yield* failFramework(`Timed out waiting for the next dev server at ${options.url}`)(
undefined,
);
});
export interface NextjsNodeService {
readonly build: (options?: FrameworkCore.FrameworkBuildOptions) => Effect.Effect<
{
readonly distDirectory: string;
readonly clientDirectory: string;
readonly serverModules: Array<{ readonly name: string }>;
},
FrameworkCore.FrameworkError
>;
readonly dev: (
options?: FrameworkCore.FrameworkDevOptions,
) => Effect.Effect<FrameworkCore.FrameworkDevServer, FrameworkCore.FrameworkError, Scope.Scope>;
}
/**
* Build the Next.js-on-Node framework service. See the module doc for the
* `build`/`dev` semantics.
*/
export const make: (
options?: NextjsNodeOptions,
) => Effect.Effect<NextjsNodeService, never, FileSystem.FileSystem | Path.Path> = Effect.fnUntraced(
function* (options?: NextjsNodeOptions) {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const resolveRoot = (override: string | undefined) =>
Effect.sync(() => path.resolve(override ?? options?.root ?? process.cwd()));
const build: NextjsNodeService["build"] = Effect.fn(function* (
buildOptions?: FrameworkCore.FrameworkBuildOptions,
) {
const root = yield* resolveRoot(buildOptions?.root);
const nodeTarget = makeNodeTarget({ root });
const output = yield* nodeTarget.build!({ root, framework: "nextjs" }).pipe(
Effect.provideService(FileSystem.FileSystem, fs),
Effect.provideService(Path.Path, path),
Effect.mapError((error) => failFramework(error.message)(error.cause)),
);
return {
distDirectory: output.distDirectory ?? root,
clientDirectory: output.clientDirectory ?? path.join(root, ".next"),
serverModules: (output.serverModules ?? []).map((module_) => ({ name: module_.name })),
};
});
const dev: NextjsNodeService["dev"] = Effect.fn(function* (
devOptions?: FrameworkCore.FrameworkDevOptions,
) {
const root = yield* resolveRoot(devOptions?.root);
const port = devOptions?.port ?? (yield* pickEphemeralPort);
const cli = yield* resolveNextCli(root);
const host = devOptions?.host ?? "127.0.0.1";
const child = yield* spawnNextDev({ root, cli, port, host });
const url = `http://${host}:${port}`;
yield* awaitNextDevReady({ url, child });
return { url };
});
return { build, dev };
},
);