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

import * as NodeNet from "node:net";
import * as NodePath from "node:path";
import type { BindingHooks, Module, RuntimeWorker } from "@alchemy.run/cloudflare-runtime/core";
import * as Assets from "@alchemy.run/cloudflare-runtime/core/bindings/assets/Assets";
import * as DurableObjectNamespace from "@alchemy.run/cloudflare-runtime/core/bindings/DurableObjectNamespace";
import * as Service from "@alchemy.run/cloudflare-runtime/core/bindings/Service";
import { DEFAULT_COMPATIBILITY_DATE } from "@alchemy.run/cloudflare-runtime/core/internal/constants";
import * as Runtime from "@alchemy.run/cloudflare-runtime/core/Runtime";
import * as RuntimeServices from "@alchemy.run/cloudflare-runtime/core/RuntimeServices";
import * as Credentials from "@distilled.cloud/cloudflare/Credentials";
import * as NodeChildProcessSpawner from "@effect/platform-node/NodeChildProcessSpawner";
import * as NodeServices from "@effect/platform-node/NodeServices";
import type * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import type * as Scope from "effect/Scope";
import * as FrameworkCore from "../core/index.ts";
import * as Bundle from "./Bundle.ts";
import * as DevServer from "./DevServer.ts";
import * as Runner from "./Runner.ts";

/**
 * The subset of the e2e-harness `options.vite` convention this integration
 * reads: the cloudflare worker configuration (compatibility date/flags,
 * worker name/bindings/assets). Structurally compatible with
 * `CloudflareVitePluginOptions` so harness fixtures stay uniform.
 */
export interface NextjsWorkerConfig {
  readonly compatibilityDate?: string | undefined;
  readonly compatibilityFlags?: Array<string> | undefined;
  readonly worker?:
    | Omit<RuntimeWorker<BindingHooks>, "compatibilityDate" | "compatibilityFlags" | "modules">
    | undefined;
}

/** Options for the Next.js (OpenNext-based) `Framework` integration. */
export interface NextjsFrameworkOptions {
  /**
   * Cloudflare worker configuration, following the e2e harness convention
   * (`options.vite` carries compatibility date/flags and the worker's
   * name/bindings/assets).
   */
  readonly vite?: NextjsWorkerConfig | undefined;
  /** Next.js/OpenNext-specific knobs. */
  readonly nextjs?:
    | {
        /**
         * Optional explicit OpenNext config for direct framework consumers.
         * Otherwise load `open-next.config.ts` when present, or generate defaults.
         */
        readonly configPath?: string | undefined;
        /** Resource-selected cache adapters. Defaults to the read-only static-assets cache. */
        readonly cache?: "static-assets" | "kv" | undefined;
        /**
         * The command the OpenNext pipeline runs to build the Next.js app.
         * Takes precedence over an explicitly supplied OpenNext config.
         * @default "npx next build"
         */
        readonly buildCommand?: string | undefined;
        /** Skip the internal `next build` (reuse an existing `.next`). */
        readonly skipNextBuild?: boolean | undefined;
        /** Minify the OpenNext bundling steps and the final bundle pass. */
        readonly minify?: boolean | undefined;
        /**
         * Enable OpenNext debug logging and verbose workerd output in dev
         * (workerd otherwise swallows uncaught worker exceptions).
         */
        readonly debug?: boolean | undefined;
      }
    | undefined;
  /** Dev-server behavior. */
  readonly dev?:
    | {
        /**
         * - `"preview"` (default): build the OpenNext worker and serve it
         *   under `cloudflare-runtime` (workerd) — production parity, no HMR.
         * - `"hmr"`: run the real `next dev` (Turbopack HMR) in Node, with
         *   the worker's bindings proxied from `cloudflare-runtime` and
         *   planted on OpenNext's `getCloudflareContext()` contract
         *   ({@link DevServer.start}). App code runs in Node, not workerd —
         *   CF-specific runtime behavior and ISR/caching semantics still
         *   need `"preview"`.
         * @default "preview"
         */
        readonly mode?: "preview" | "hmr" | undefined;
      }
    | undefined;
  /** Project root. Defaults to the process working directory. */
  readonly root?: string | undefined;
  /**
   * The host's runtime stack (a `Context.Context<RuntimeServices>`, e.g.
   * alchemy's `DevContext.runtimeContext`). When provided, dev servers host
   * the binding proxy in it instead of building the credential-free internal
   * layer — this is what makes `Alchemy.remote()` bindings resolve in dev.
   * Typed `unknown` to keep the option JSON-tolerant at the boundary; it is
   * narrowed internally.
   */
  readonly services?: unknown;
}

/**
 * Extract the edge-runtime function paths from `.next/server/
 * middleware-manifest.json`. `middleware` entries are supported (OpenNext
 * runs the middleware in the worker); `functions` entries are routes/pages
 * compiled for the edge runtime, which `@opennextjs/cloudflare` does not
 * support.
 */
export const listEdgeFunctions = (manifest: unknown): Array<string> => {
  if (typeof manifest !== "object" || manifest === null) return [];
  const functions = (manifest as { functions?: Record<string, unknown> }).functions;
  return functions === undefined ? [] : Object.keys(functions);
};

export { DEFAULT_COMPATIBILITY_DATE };

/** The server-module name of the worker entry (`serverModules[0]`). */
export const WORKER_ENTRY_MODULE = `worker/${Bundle.WORKER_ENTRY_NAME}`;

/** The OpenNext revalidation-queue Durable Object class. */
export const DO_QUEUE_CLASS = "DOQueueHandler";
/** The binding name OpenNext expects for the revalidation-queue DO. */
export const DO_QUEUE_BINDING = "NEXT_CACHE_DO_QUEUE";
/** The self service binding OpenNext uses for ISR revalidation fetches. */
export const SELF_REFERENCE_BINDING = "WORKER_SELF_REFERENCE";

/** Build the {@link Runner.RunnerConfig} for a project (exported for testing). */
export const makeRunnerConfig = (
  root: string,
  options?: NextjsFrameworkOptions,
): Runner.RunnerConfig => ({
  appDir: root,
  configPath: options?.nextjs?.configPath,
  cache: options?.nextjs?.cache ?? "static-assets",
  compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
  skipNextBuild: options?.nextjs?.skipNextBuild ?? false,
  minify: options?.nextjs?.minify ?? false,
  debug: options?.nextjs?.debug ?? false,
  buildCommand: options?.nextjs?.buildCommand,
});

/**
 * Map a `BuildOutput`'s server modules to cloudflare-runtime worker modules
 * (exported for testing). Sourcemaps are dropped; binary content is passed
 * through as bytes, text content as strings.
 */
export const toRuntimeModules = (
  serverModules: ReadonlyArray<FrameworkCore.OutputFile>,
): Array<Module> =>
  serverModules.flatMap((file): Module | Array<Module> => {
    const asText = () =>
      typeof file.content === "string" ? file.content : Buffer.from(file.content).toString("utf8");
    const asBytes = () =>
      typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content;
    switch (NodePath.extname(file.name)) {
      case ".js":
      case ".mjs":
        return { name: file.name, type: "ESModule", content: asText() };
      case ".cjs":
        return { name: file.name, type: "CommonJsModule", content: asText() };
      case ".json":
        return { name: file.name, type: "Json", content: asText() };
      case ".wasm":
        return { name: file.name, type: "Wasm", content: asBytes() };
      case ".bin":
        return { name: file.name, type: "Data", content: asBytes() };
      case ".map":
        return [];
      default:
        return { name: file.name, type: "Text", content: asText() };
    }
  });

/**
 * Whether the entry module exports the OpenNext revalidation-queue Durable
 * Object class (exported for testing). OpenNext's `worker.js` re-exports the
 * DO classes it ships; when present, dev declares the same-script
 * SQLite-backed namespace + binding so `doQueue`-configured apps work and
 * `memoryQueue` apps keep parity with the deployed worker shape.
 */
export const hasDoQueueClass = (entry: FrameworkCore.OutputFile | undefined): boolean => {
  if (entry === undefined) return false;
  const content =
    typeof entry.content === "string" ? entry.content : Buffer.from(entry.content).toString("utf8");
  return content.includes(DO_QUEUE_CLASS);
};

/** The services the runtime layer for dev is built from. */
const makeRuntimeLayer = () =>
  RuntimeServices.layerRuntime({
    api: {
      // Local-only serving: the account id is only consulted when remote
      // bindings are used, which a preview-parity dev server does not
      // require. Fall back to a placeholder so credentials stay optional.
      accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "distilled-nextjs-local",
    },
  }).pipe(
    Layer.provideMerge(NodeServices.layer),
    Layer.provide(Layer.merge(Credentials.fromEnv(), FetchHttpClient.layer)),
  );

/**
 * Front a target server with a TCP proxy on a fixed local port.
 * `Runtime.start` always binds an ephemeral port, so honoring
 * `FrameworkDevOptions.port` requires the forwarder.
 */
const proxyToPort = (
  port: number,
  target: URL,
): Effect.Effect<URL, FrameworkCore.FrameworkError, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.callback<NodeNet.Server, FrameworkCore.FrameworkError>((resume) => {
      const server = NodeNet.createServer((socket) => {
        const upstream = NodeNet.connect(Number(target.port), target.hostname);
        socket.pipe(upstream);
        upstream.pipe(socket);
        const teardown = () => {
          socket.destroy();
          upstream.destroy();
        };
        socket.on("error", teardown);
        upstream.on("error", teardown);
        socket.on("close", teardown);
        upstream.on("close", teardown);
      });
      server.once("error", (cause) =>
        resume(
          Effect.fail(
            new FrameworkCore.FrameworkError({
              framework: "nextjs",
              message: `Failed to listen on port ${port}`,
              cause,
            }),
          ),
        ),
      );
      server.listen(port, "127.0.0.1", () => resume(Effect.succeed(server)));
    }),
    (server) =>
      Effect.callback<void>((resume) => {
        server.close(() => resume(Effect.void));
      }),
  ).pipe(Effect.map(() => new URL(`http://127.0.0.1:${port}`)));

/**
 * The Next.js implementation of framework-core's `Framework` service,
 * built on the `@opennextjs/cloudflare` build pipeline — wrangler-free:
 *
 * - `build` runs the pipeline in a disposable child process (`runner.mjs`
 *   vendors the two thin config wrappers so no wrangler code is ever
 *   imported), then performs the final bundle pass wrangler would normally
 *   do at deploy time ({@link Bundle.bundleWorker}), populates the
 *   static-assets incremental cache, and returns the `BuildOutput` in-memory.
 * - `dev` (default mode `"preview"`) serves the built worker under
 *   `@alchemy.run/cloudflare-runtime/core` (workerd) with the OpenNext worker
 *   shape: `ASSETS` + run-worker-first, a `WORKER_SELF_REFERENCE` self
 *   service binding, and the same-script SQLite-backed revalidation-queue
 *   Durable Object. No HMR — file watching/rebuild is a later phase.
 * - `dev` with `options.dev.mode: "hmr"` runs the real `next dev` (Turbopack
 *   HMR) in Node with the worker's bindings proxied from
 *   `cloudflare-runtime` ({@link DevServer.start}) — see the mode's fidelity
 *   notes on {@link NextjsFrameworkOptions}.
 */
export const make = (
  options?: NextjsFrameworkOptions,
): Layer.Layer<FrameworkCore.Framework, never, FileSystem.FileSystem | Path.Path> =>
  Layer.effect(
    FrameworkCore.Framework,
    Effect.gen(function* () {
      const fs = yield* FileSystem.FileSystem;
      const path = yield* Path.Path;

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

      const spawnerLayer = NodeChildProcessSpawner.layer.pipe(
        Layer.provide(
          Layer.merge(Layer.succeed(FileSystem.FileSystem)(fs), Layer.succeed(Path.Path)(path)),
        ),
      );

      const resolveRoot = (override: string | undefined) =>
        Effect.sync(() => path.resolve(override ?? options?.root ?? process.cwd()));

      const paths = (root: string, openNextDirectory: string) => ({
        openNextDirectory,
        clientDirectory: path.join(openNextDirectory, "assets"),
        cacheDirectory: path.join(openNextDirectory, "cache"),
        distDirectory: path.resolve(root, "dist"),
        workerDirectory: path.resolve(root, "dist", "worker"),
      });

      const build = Effect.fn(function* (buildOptions?: FrameworkCore.FrameworkBuildOptions) {
        const root = yield* resolveRoot(buildOptions?.root);
        // 1. The OpenNext build pipeline (spawns `next build` internally).
        const buildPaths = yield* Runner.runOpenNextBuild(makeRunnerConfig(root, options)).pipe(
          Effect.mapError((error) => fail(error.message)(error.cause)),
          Effect.provide(spawnerLayer),
          Effect.provideService(FileSystem.FileSystem, fs),
          Effect.provideService(Path.Path, path),
        );
        const p = paths(root, buildPaths.openNextDirectory);

        // 1.5. Edge-runtime routes/pages are not supported by
        // @opennextjs/cloudflare (it shims `next/dist/compiled/edge-runtime`
        // to an empty module, so they 500 at runtime). Fail the build with
        // the exact route list instead of shipping a mystery 500 — the same
        // code runs fine on Workers under the node runtime.
        const manifestPath = path.join(
          buildPaths.appBuildOutputPath,
          ".next",
          "server",
          "middleware-manifest.json",
        );
        const manifestRaw = yield* fs
          .readFileString(manifestPath)
          .pipe(Effect.orElseSucceed(() => undefined));
        if (manifestRaw !== undefined) {
          const edgeRoutes = yield* Effect.try({
            try: () => listEdgeFunctions(JSON.parse(manifestRaw)),
            catch: fail(`Failed to parse ${manifestPath}`),
          });
          if (edgeRoutes.length > 0) {
            return yield* fail(
              `Edge-runtime routes/pages are not supported by @opennextjs/cloudflare: ${edgeRoutes.join(", ")}. ` +
                `Remove \`export const runtime = "edge"\` from these modules — the node runtime runs on Workers.`,
            )(undefined);
          }
        }

        // 2. The final bundle pass (what wrangler does implicitly on deploy).
        yield* fs.remove(p.workerDirectory, { recursive: true }).pipe(Effect.ignore);
        yield* Bundle.bundleWorker({
          openNextDirectory: p.openNextDirectory,
          outDirectory: p.workerDirectory,
          minify: options?.nextjs?.minify ?? false,
        }).pipe(Effect.mapError((error) => fail(error.message)(error.cause)));

        // 3. populateCache, static-assets flavor: prerendered ISR/fetch cache
        //    entries are served read-only through the ASSETS binding.
        const hasCache = yield* fs.exists(p.cacheDirectory).pipe(Effect.orElseSucceed(() => false));
        if (hasCache) {
          yield* fs
            .copy(p.cacheDirectory, path.join(p.clientDirectory, "cdn-cgi", "_next_cache"), {
              overwrite: true,
            })
            .pipe(Effect.mapError(fail("Failed to populate the static-assets incremental cache")));
        }

        // 4. Collect the BuildOutput contract from disk (entry first).
        const files = yield* FrameworkCore.readServerModulesFromDisk({
          directory: p.workerDirectory,
          prefix: "worker",
        }).pipe(
          Effect.provideService(FileSystem.FileSystem, fs),
          Effect.mapError((error) => fail(error.message)(error.cause)),
        );
        const output: FrameworkCore.BuildOutput = {
          distDirectory: p.distDirectory,
          clientDirectory: p.clientDirectory,
          serverModules: FrameworkCore.sortServerModules(files, WORKER_ENTRY_MODULE),
          externalWorkspaces: new Set(),
        };
        return output;
      });

      // The runtime context the dev servers host their binding proxy in:
      // the caller-provided host stack (includes remote-bindings support,
      // so `Alchemy.remote()` bindings resolve) when present, the internal
      // credential-free layer otherwise.
      const resolveRuntimeContext = Effect.fn(function* () {
        if (options?.services !== undefined) {
          return options.services as Context.Context<RuntimeServices.RuntimeServices>;
        }
        const scope = yield* Effect.scope;
        return yield* Layer.buildWithScope(makeRuntimeLayer(), scope).pipe(
          Effect.mapError(fail("Failed to start the cloudflare-runtime services")),
        );
      });

      const dev = Effect.fn(function* (devOptions?: FrameworkCore.FrameworkDevOptions) {
        const root = yield* resolveRoot(devOptions?.root);

        // Dev v2 ("hmr"): real `next dev` (Turbopack HMR) in Node, bindings
        // proxied from cloudflare-runtime onto OpenNext's
        // getCloudflareContext() contract. No OpenNext build involved.
        if (options?.dev?.mode === "hmr") {
          const worker = options?.vite?.worker;
          const context = yield* resolveRuntimeContext();
          const server = yield* DevServer.start({
            root,
            port: devOptions?.port,
            bindings: worker?.bindings ?? [],
            compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
            compatibilityFlags: [
              ...new Set(["nodejs_compat", ...(options?.vite?.compatibilityFlags ?? [])]),
            ],
            ...(worker?.name !== undefined ? { proxyName: `${worker.name}-dev-proxy` } : {}),
            ...(worker?.workerd !== undefined ? { workerd: worker.workerd } : {}),
            logging: options?.nextjs?.debug ? { verbose: true } : worker?.logging,
          }).pipe(Effect.provideContext(context));
          return { url: server.url.href };
        }

        // Preview parity: always build on dev start (OpenNext memoizes where
        // it can). Watch + rebuild is a later phase.
        const output = yield* build({ root });
        if (output.serverModules === undefined || output.serverModules.length === 0) {
          return yield* fail("The build produced no server modules")(undefined);
        }
        const modules = toRuntimeModules(output.serverModules);
        const worker = options?.vite?.worker;

        const declaresDoQueue = (worker?.durableObjectNamespaces ?? []).some(
          (namespace) => namespace.className === DO_QUEUE_CLASS,
        );
        const withDoQueue = !declaresDoQueue && hasDoQueueClass(output.serverModules[0]);

        const context = yield* resolveRuntimeContext();

        const url = yield* Runtime.Runtime.use((runtime) =>
          runtime.start({
            name: worker?.name ?? "distilled-nextjs-dev",
            compatibilityDate: options?.vite?.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
            compatibilityFlags: [
              ...new Set(["nodejs_compat", ...(options?.vite?.compatibilityFlags ?? [])]),
            ],
            modules,
            bindings: [
              Assets.local("ASSETS"),
              Service.self(SELF_REFERENCE_BINDING),
              ...(withDoQueue
                ? [
                    DurableObjectNamespace.local({
                      binding: DO_QUEUE_BINDING,
                      className: DO_QUEUE_CLASS,
                    }),
                  ]
                : []),
              ...(worker?.bindings ?? []),
            ],
            assets: {
              ...worker?.assets,
              directory: output.clientDirectory,
              runWorkerFirst: worker?.assets?.runWorkerFirst ?? true,
            },
            durableObjectNamespaces: [
              ...(withDoQueue ? [{ className: DO_QUEUE_CLASS, sql: true }] : []),
              ...(worker?.durableObjectNamespaces ?? []),
            ],
            ...(worker?.hyperdrives !== undefined ? { hyperdrives: worker.hyperdrives } : {}),
            ...(worker?.queueConsumers !== undefined
              ? { queueConsumers: worker.queueConsumers }
              : {}),
            ...(worker?.unsafe !== undefined ? { unsafe: worker.unsafe } : {}),
            ...(worker?.workerd !== undefined ? { workerd: worker.workerd } : {}),
            logging: options?.nextjs?.debug ? { verbose: true } : worker?.logging,
          }),
        ).pipe(
          Effect.provideContext(context),
          Effect.mapError(fail("Failed to start the dev worker in cloudflare-runtime")),
        );

        if (devOptions?.port !== undefined && String(devOptions.port) !== url.port) {
          const proxied = yield* proxyToPort(devOptions.port, url);
          return { url: proxied.href };
        }
        return { url: url.href };
      });

      return FrameworkCore.Framework.of({
        build: (buildOptions) => build(buildOptions),
        dev: (devOptions) => dev(devOptions),
      });
    }),
  );