sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Website/ Nextjs.ts

import { DEFAULT_COMPATIBILITY_DATE } from "@alchemy.run/cloudflare-runtime/core/internal/constants";
import type { MemoOptions } from "alchemy/Command/Memo";
import type { InputProps } from "alchemy/Input";
import { effectClass } from "alchemy/Util/effect";
import * as Effect from "effect/Effect";
import type { Namespace } from "../KV/Namespace.ts";
import type { Providers } from "../Providers.ts";
import type { AssetsConfig } from "../Workers/Assets.ts";
import { DurableObject } from "../Workers/DurableObject.ts";
import {
  Self,
  Worker,
  type NormalizedBindings,
  type WorkerAssetsConfig,
  type WorkerBindingProps,
  type WorkerProps,
} from "../Workers/Worker.ts";

/**
 * The module specifier of the Next.js source provider. Loaded with a
 * dynamic `import()`, so `@alchemy.run/frontend-frameworks` must be installed
 * in the deploying project. The provider is exposed through its `/nextjs`
 * subpath.
 */
const NEXTJS_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/nextjs/source";

export interface NextjsProps<Bindings extends WorkerBindingProps = {}> extends Omit<
  WorkerProps<Bindings>,
  "vite" | "main" | "assets" | "script" | "bundle" | "source" | "rules" | "dev"
> {
  /**
   * The Next.js project root. Defaults to the process working directory.
   */
  rootDir?: string;
  /**
   * Controls which files are content-hashed to decide whether the OpenNext
   * build needs to re-run. By default every project file outside build
   * outputs (`.next`, `.open-next`, `dist`) and `node_modules` is hashed,
   * plus the nearest package-manager lockfile. Narrow the scope with
   * `include`/`exclude` globs when the default is too broad.
   * `open-next.config.ts` itself is always hashed. When narrowing `include`,
   * also include any helpers imported by that config.
   */
  memo?: MemoOptions;
  /**
   * Binds KV caches and the same-worker Durable Object revalidation queue.
   * Without `open-next.config.ts`, Alchemy selects matching KV adapters;
   * omitting `isr` instead selects the read-only static-assets cache.
   * A native config controls adapter selection and must choose adapters
   * matching these bindings. KV fills on demand; build-time cache entries
   * are not uploaded to KV.
   */
  isr?: {
    /** KV namespace storing rendered pages and fetch results. */
    incrementalCache: Namespace;
    /** KV namespace storing cache-tag invalidations. */
    tagCache: Namespace;
  };
  /** Build controls, separate from the optional native `open-next.config.ts`. */
  openNext?: {
    /**
     * Overrides the native config's `buildCommand` when set. If neither sets
     * a command, defaults to `npx next build`.
     */
    buildCommand?: string;
    /** Minify the generated Worker. Defaults to false. */
    minify?: boolean;
    /** Enable OpenNext build diagnostics. Defaults to false. */
    debug?: boolean;
  };
  /**
   * Local dev (`alchemy dev`) behavior.
   */
  dev?: {
    /**
     * - `"preview"` (default): build the OpenNext worker and serve it
     *   under workerd — production parity (workerd APIs, ISR/cache
     *   semantics), no HMR.
     * - `"hmr"`: run the real `next dev` (Turbopack HMR) in Node with the
     *   Worker's bindings proxied onto OpenNext's `getCloudflareContext()`
     *   contract. App code runs in Node, not workerd — CF-specific
     *   runtime behavior still needs `"preview"`.
     * @default "preview"
     */
    mode?: "preview" | "hmr";
    /**
     * Port for the local dev server. `0` picks an ephemeral port.
     */
    port?: number;
  };
  /**
   * Optional configuration for static asset routing behavior.
   * Defaults to `runWorkerFirst: true` with `htmlHandling`/`notFoundHandling`
   * set to `"none"` — the OpenNext server owns routing and delegates to the
   * `ASSETS` binding itself.
   */
  assets?: AssetsConfig;
}

// These options are inspected while constructing the Worker. Resolve them in
// the outer props Effect; pass-through properties can remain deferred Inputs.
type NextjsInput<Bindings extends WorkerBindingProps> = InputProps<
  NextjsProps<Bindings>,
  "dev" | "isr" | "env" | "compatibility" | "assets" | "openNext"
>;

/**
 * A Cloudflare Worker deployed from a Next.js project.
 *
 * `Nextjs` builds the app with the wrangler-free OpenNext pipeline from
 * [`@alchemy.run/frontend-frameworks/nextjs`](https://github.com/alchemy-run/alchemy/tree/main/packages/frontend-frameworks/src/nextjs):
 * `next build` runs through `@opennextjs/cloudflare`, the resulting worker
 * is bundled into a self-contained ES module set, and the static assets
 * (including prerendered pages and the read-only incremental cache) deploy
 * as Workers static assets. Input files are content-hashed so unchanged
 * projects skip the build and deploy entirely.
 *
 * Both `@alchemy.run/frontend-frameworks` and its peer
 * `@opennextjs/cloudflare` must be installed in the deploying project. The
 * source provider is loaded from the package's `/nextjs` export with a dynamic
 * `import()`.
 *
 * Local dev (`alchemy dev`) defaults to preview parity — the built worker
 * served under workerd. Set `dev: { mode: "hmr" }` for the real `next dev`
 * (Turbopack HMR) with the Worker's bindings proxied onto
 * `getCloudflareContext()`.
 *
 * If `open-next.config.ts` exists in the project root, Alchemy loads it through
 * OpenNext's native compiler without rewriting it. Otherwise, Alchemy generates
 * temporary defaults: a read-only static-assets cache, or KV adapters when
 * `isr` is set. Static-assets revalidation writes are a no-op.
 * Native Next.js and Tailwind configuration files are left unchanged.
 *
 * Known limitations (upstream `@opennextjs/cloudflare`):
 * - Edge-runtime routes/pages (`export const runtime = "edge"`) are not
 *   supported — the build fails with the offending route list; remove the
 *   directive (the node runtime runs on Workers). Middleware is fine.
 * - `next/image` optimization requires a zone with Cloudflare Images;
 *   on `workers.dev`, use `unoptimized` (images serve as raw assets).
 * - Partial Prerendering / `"use cache"` (`cacheComponents`) and
 *   Pages-Router `i18n` config are untested/out of scope for now. App
 *   Router i18n via middleware works (middleware is fully supported).
 *
 *
 * ### Deploying a Next.js App
 * A single call builds the app and deploys the Worker plus static assets.
 * No `open-next.config.ts`, Wrangler config, or Alchemy plugin is required.
 *
 * **Example:** Basic Next.js site
 * ```typescript
 * const site = yield* Cloudflare.Website.Nextjs("Site");
 * ```
 *
 * **Example:** Explicit project root
 * ```typescript
 * const site = yield* Cloudflare.Website.Nextjs("Site", {
 *   rootDir: "./apps/web",
 * });
 * ```
 *
 * ### Optional Native OpenNext Configuration
 * The same `Cloudflare.Website.Nextjs("Site")` call works with or without a
 * config file. To customize OpenNext, add `open-next.config.ts` under `rootDir`
 * (the working directory by default). Imports and callbacks are preserved;
 * the native `OpenNextConfig` is passed to OpenNext's compiler, subject to
 * Cloudflare's adapter constraints rather than AWS runtime feature parity.
 *
 * **Example:** Native config with the read-only static-assets cache
 * ```typescript
 * // open-next.config.ts
 * import { defineCloudflareConfig, type OpenNextConfig } from "@opennextjs/cloudflare";
 * import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache";
 *
 * export default {
 *   ...defineCloudflareConfig({ incrementalCache: staticAssetsIncrementalCache }),
 *   buildCommand: "pnpm exec next build",
 * } satisfies OpenNextConfig;
 * ```
 *
 * ### Bindings
 * Resources passed via `env` become Worker bindings, readable in route
 * handlers and server components through OpenNext's
 * `getCloudflareContext()`.
 *
 * **Example:** Binding an R2 bucket
 * ```typescript
 * const bucket = yield* Cloudflare.R2.Bucket("Uploads");
 * const site = yield* Cloudflare.Website.Nextjs("Site", {
 *   env: {
 *     UPLOADS: bucket,
 *   },
 * });
 * ```
 *
 * ```typescript
 * // app/api/upload/route.ts
 * import { getCloudflareContext } from "@opennextjs/cloudflare";
 *
 * export async function PUT(request: Request) {
 *   const { env } = getCloudflareContext();
 *   await env.UPLOADS.put("key", await request.text());
 *   return Response.json({ ok: true });
 * }
 * ```
 *
 * ### Writable ISR
 * Supply the cache namespaces on the resource. Alchemy binds them and adds
 * the Durable Object queue for background regeneration. Without a native
 * config, it also selects the matching adapters. With a native config, select
 * `kv-incremental-cache`, `kv-next-tag-cache`, and `do-queue` there; `isr`
 * does not override the file's adapter choices.
 *
 * **Example:** Binding the writable-ISR resources
 * ```typescript
 * const incCache = yield* Cloudflare.KV.Namespace("NextIncCache");
 * const tagCache = yield* Cloudflare.KV.Namespace("NextTagCache");
 *
 * const site = yield* Cloudflare.Website.Nextjs("Site", {
 *   isr: { incrementalCache: incCache, tagCache },
 * });
 * ```
 *
 * ### Custom Rebuild Scope
 * By default, every project file outside build outputs is hashed to decide
 * whether a rebuild is needed. Use `memo` to narrow the scope when the
 * project has large directories that don't affect the build output.
 * `open-next.config.ts` itself is always hashed. Include any imported config
 * helpers in a narrowed `memo.include` too (for example, `config/**`).
 *
 * **Example:** Narrowing the memo scope
 * ```typescript
 * const site = yield* Cloudflare.Website.Nextjs("Site", {
 *   memo: {
 *     include: ["app/**", "public/**", "package.json", "next.config.mjs", "config/**"],
 *   },
 * });
 * ```
 *
 * ### Build Configuration
 * An explicit `openNext.buildCommand` overrides the native config's command.
 * `openNext.minify` and `openNext.debug` remain resource-level build controls.
 *
 * **Example:** Customize the build
 * ```typescript
 * const site = yield* Cloudflare.Website.Nextjs("Site", {
 *   openNext: { buildCommand: "pnpm exec next build", minify: true },
 * });
 * ```
 *
 * ### Class Form
 * Calling `Nextjs` with no arguments returns a constructor you can
 * `extend` to declare the Worker as a named class. The class is both an
 * `Effect` you can `yield*` to deploy and a type you can reference
 * elsewhere — useful when other resources need to bind to this Worker.
 *
 * **Example:** Declaring a Worker class
 * ```typescript
 * class Site extends Cloudflare.Website.Nextjs<Site>()("Site", {
 *   rootDir: "./apps/web",
 * }) {}
 *
 * const site = yield* Site;
 * ```
 *
 * @resource
 * @product Website
 * @category Workers & Compute
 */
export const Nextjs: {
  <Self>(): {
    <const Bindings extends WorkerBindingProps = {}, Req = never>(
      id: string,
      propsEff?: NextjsInput<Bindings> | Effect.Effect<NextjsInput<Bindings>, never, Req>,
    ): Effect.Effect<Self, never, Req | Providers> & {
      new (): Worker<{
        [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
          Bindings,
          WorkerAssetsConfig
        >[binding];
      }>;
    };
  };
  <const Bindings extends WorkerBindingProps = {}, Req = never>(
    id: string,
    propsEff?: NextjsInput<Bindings> | Effect.Effect<NextjsInput<Bindings>, never, Req>,
  ): Effect.Effect<
    Worker<{
      [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
        Bindings,
        WorkerAssetsConfig
      >[binding];
    }>,
    never,
    Req | Providers
  >;
} = (<const Bindings extends WorkerBindingProps = {}, Req = never>(
  id?: string,
  propsEff?: NextjsInput<Bindings> | Effect.Effect<NextjsInput<Bindings>, never, Req>,
) =>
  id === undefined
    ? <const Bindings extends WorkerBindingProps = {}, Req = never>(
        id: string,
        propsEff?: NextjsInput<Bindings> | Effect.Effect<NextjsInput<Bindings>, never, Req>,
      ) => effectClass(Nextjs(id, propsEff))
    : Worker(
        id,
        Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => ({
          ...props,
          // `dev.mode` is the integration's dev behavior (routed through
          // the source options below); only `port` maps onto the Worker's
          // own local-dev config.
          dev: props?.dev?.port !== undefined ? { port: props.dev.port } : undefined,
          // OpenNext's revalidation queues (memory-queue, do-queue) fetch
          // the worker back through `WORKER_SELF_REFERENCE`. Always wire
          // the self service binding — it's inert when unused, and its
          // absence turns ISR revalidation into a silent no-op. An
          // explicit user-provided `env.WORKER_SELF_REFERENCE` wins.
          env: {
            WORKER_SELF_REFERENCE: Self,
            ...props?.env,
            ...(props?.isr
              ? {
                  NEXT_INC_CACHE_KV: props.isr.incrementalCache,
                  NEXT_TAG_CACHE_KV: props.isr.tagCache,
                  NEXT_CACHE_DO_QUEUE: DurableObject("NEXT_CACHE_DO_QUEUE", {
                    className: "DOQueueHandler",
                  }),
                }
              : {}),
          },
          // OpenNext requires Node.js APIs. The 2026-08-31 default date
          // enables both nodejs_compat modes, so no redundant flag is sent.
          compatibility: {
            date: props?.compatibility?.date ?? DEFAULT_COMPATIBILITY_DATE,
            flags: props?.compatibility?.flags,
          },
          // The OpenNext server owns routing: run the worker first and
          // leave asset-path rewriting off. Users can still override.
          assets: {
            runWorkerFirst: true,
            htmlHandling: "none" as const,
            notFoundHandling: "none" as const,
            ...props?.assets,
          },
          source: {
            provider: NEXTJS_SOURCE_PROVIDER,
            devMode: "server",
            rootDir: props?.rootDir,
            // `next dev` (Turbopack) cold-starts broken under bun (every
            // route 404s until `.next` is warm) — pin the dev child to node.
            runtime: "node",
            options: {
              root: props?.rootDir,
              memo: props?.memo,
              cache: props?.isr ? "kv" : "static-assets",
              ...props?.openNext,
              ...(props?.dev?.mode !== undefined ? { dev: { mode: props.dev.mode } } : {}),
            },
          },
        })),
      )) as any;