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

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 { Providers } from "../Providers.ts";
import type { AssetsConfig } from "../Workers/Assets.ts";
import {
  Worker,
  type NormalizedBindings,
  type WorkerAssetsConfig,
  type WorkerBindingProps,
  type WorkerProps,
} from "../Workers/Worker.ts";

/**
 * The specifier of the Waku source-provider module. The package must be
 * installed in the user's project — `loadSource` fails with a
 * `SourceProviderError` naming it otherwise.
 */
const WAKU_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/waku/source";

export interface WakuProps<Bindings extends WorkerBindingProps = {}> extends Omit<
  WorkerProps<Bindings>,
  "vite" | "main" | "assets" | "source" | "script" | "bundle" | "rules"
> {
  /**
   * Overrides the module that becomes the deployed Worker entry. Relative
   * paths resolve from {@link rootDir}.
   *
   * By default Waku's own RSC server entry is deployed. Point `main` at a
   * custom module when the deployed Worker must export more than Waku's
   * fetch handler — e.g. Durable Object classes or additional handlers.
   * The custom entry wraps Waku's handler by importing it from
   * `virtual:waku/server-entry` and re-exports the extras:
   *
   * ```typescript
   * // src/worker-entry.ts
   * import wakuHandler from "virtual:waku/server-entry";
   * export class Counter extends DurableObject {}
   * export default {
   *   fetch: (request, env, ctx) => wakuHandler.fetch(request, env, ctx),
   * };
   * ```
   */
  main?: string;
  /**
   * Root directory of the Waku project. Defaults to the process working
   * directory.
   */
  rootDir?: string;
  /**
   * Controls which files feed the content hash that decides whether a
   * rebuild is needed. By default every non-gitignored file under
   * {@link rootDir} is hashed, plus the nearest package-manager lockfile.
   * Provide `include`/`exclude` globs to narrow the scope.
   */
  memo?: MemoOptions;
  /**
   * Optional configuration for static asset routing behavior.
   * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
   *
   * Waku links SSG pages without trailing slashes (`/about`), so
   * `htmlHandling` defaults to `"drop-trailing-slash"` — the prerendered
   * `about/index.html` serves directly at `/about` instead of 307-redirecting
   * to `/about/`. Set `htmlHandling` explicitly to override.
   *
   * @default { htmlHandling: "drop-trailing-slash" }
   */
  assets?: AssetsConfig;
  /**
   * Waku config overrides merged over the project's `waku.config.*`
   * (per-key; deploy-time values win). For values that vary by stage or
   * come from other resources — static config belongs in `waku.config.*`.
   */
  waku?: {
    /**
     * Waku `srcDir` (relative to {@link rootDir}).
     * @default "src"
     */
    srcDir?: string;
    /**
     * Waku `distDir` (relative to {@link rootDir}). If `waku.config.*`
     * customizes `distDir`, mirror it here (or add it to `memo.exclude`)
     * so the build output stays excluded from the rebuild-deciding input
     * hash.
     * @default "dist"
     */
    distDir?: string;
    /**
     * Waku `basePath`.
     * @default "/"
     */
    basePath?: string;
  };
}

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

/**
 * A Cloudflare Worker deployed from a [Waku](https://waku.gg) project.
 *
 * `Waku` builds the project programmatically — no `waku.config.ts` edits,
 * no Wrangler configuration, and no build command required. A project's
 * `waku.config.*` loads natively (same as waku's CLI) and is where all
 * Waku configuration (`srcDir`, `distDir`, `basePath`, ...) lives; the
 * `waku` prop overrides it per key at deploy time.
 * `unstable_adapter` is owned by Alchemy and must not be set. Note that a
 * standalone `vite.config.ts` is NOT loaded (same as waku's CLI) — Vite
 * config belongs in `waku.config.*`'s `vite` field. The RSC server
 * bundle deploys as the Worker script and the client output (including
 * SSG-prerendered pages) deploys as static assets.
 *
 * Requires the `@alchemy.run/frontend-frameworks` package to be installed in
 * your project; the integration is loaded from its `/waku` export. Input files
 * are content-hashed
 * (respecting `.gitignore` by default) so unchanged projects skip the
 * build and deploy entirely.
 *
 * Waku's server runtime uses `AsyncLocalStorage`, so the `nodejs_als`
 * compatibility flag is enabled automatically when your compatibility
 * flags include neither `nodejs_als` nor `nodejs_compat`. SSG pages are
 * served at their extensionless URLs (`/about`) via the default
 * `drop-trailing-slash` asset handling.
 *
 *
 * ### Deploying a Waku Site
 * A single call builds the project and deploys the RSC server bundle plus
 * the client assets — no configuration required.
 *
 * **Example:** Waku site
 * ```typescript
 * const site = yield* Cloudflare.Website.Waku("Site");
 * ```
 *
 * **Example:** Waku project in a subdirectory
 * ```typescript
 * const site = yield* Cloudflare.Website.Waku("Site", {
 *   rootDir: "apps/web",
 * });
 * ```
 *
 * ### Waku Config Overrides
 * Waku configuration lives in your `waku.config.*`. The `waku` prop
 * overrides it per key at deploy time — for values that vary by stage
 * or come from other resources.
 *
 * **Example:** Stage-dependent base path
 * ```typescript
 * const site = yield* Cloudflare.Website.Waku("Site", {
 *   waku: {
 *     basePath: "/docs/",
 *   },
 * });
 * ```
 *
 * ### Bindings
 * Pass resources through `env` like any other Worker. Server components
 * and API routes read them from the `cloudflare:workers` env at request
 * time. Prefer a guarded dynamic import in page modules — Waku's SSG step
 * renders static pages in Node, where a top-level
 * `import { env } from "cloudflare:workers"` cannot resolve.
 *
 * **Example:** Binding an R2 bucket
 * ```typescript
 * const bucket = yield* Cloudflare.R2.Bucket("Uploads");
 *
 * const site = yield* Cloudflare.Website.Waku("Site", {
 *   env: {
 *     UPLOADS: bucket,
 *   },
 * });
 * ```
 *
 * ### Custom Worker Entry
 * By default the deployed Worker entry is Waku's own RSC server entry.
 * When the Worker must export more than Waku's fetch handler — Durable
 * Object classes, additional handlers — point `main` at your own module
 * that wraps Waku's handler (imported from `virtual:waku/server-entry`)
 * and re-exports the extras.
 *
 * **Example:** Custom entry hosting a Durable Object
 * ```typescript
 * // src/worker-entry.ts
 * // import wakuHandler from "virtual:waku/server-entry";
 * // export class Counter extends DurableObject { ... }
 * // export default { fetch: (req, env, ctx) => wakuHandler.fetch(req, env, ctx) };
 *
 * const site = yield* Cloudflare.Website.Waku("Site", {
 *   main: "src/worker-entry.ts",
 *   env: {
 *     COUNTER: Cloudflare.DurableObject("Counter", {
 *       className: "Counter",
 *     }),
 *   },
 * });
 * ```
 *
 * ### Custom Rebuild Scope
 * By default, every non-gitignored file is hashed to decide whether a
 * rebuild is needed. Use `memo` to narrow the scope when your project has
 * large directories that don't affect the build output.
 *
 * **Example:** Narrowing the memo scope
 * ```typescript
 * const site = yield* Cloudflare.Website.Waku("Site", {
 *   memo: {
 *     include: ["src/**", "public/**", "package.json"],
 *   },
 * });
 * ```
 *
 * ### Class Form
 * Calling `Waku` 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 Waku Worker class
 * ```typescript
 * class Site extends Cloudflare.Website.Waku<Site>()("Site") {}
 *
 * const site = yield* Site;
 * ```
 *
 * @resource
 * @product Website
 * @category Workers & Compute
 */
export const Waku: {
  <Self>(): {
    <const Bindings extends WorkerBindingProps = {}, Req = never>(
      id: string,
      propsEff?: WakuInput<Bindings> | Effect.Effect<WakuInput<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?: WakuInput<Bindings> | Effect.Effect<WakuInput<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?: WakuInput<Bindings> | Effect.Effect<WakuInput<Bindings>, never, Req>,
) =>
  id === undefined
    ? <const Bindings extends WorkerBindingProps = {}, Req = never>(
        id: string,
        propsEff?: WakuInput<Bindings> | Effect.Effect<WakuInput<Bindings>, never, Req>,
      ) => effectClass(Waku(id, propsEff))
    : Worker(
        id,
        Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => ({
          ...props,
          compatibility: {
            ...props?.compatibility,
            // Waku's server runtime needs AsyncLocalStorage — default to
            // nodejs_als when the user hasn't enabled it (or the broader
            // nodejs_compat) themselves.
            flags:
              props?.compatibility?.flags?.includes("nodejs_als") ||
              props?.compatibility?.flags?.includes("nodejs_compat")
                ? props.compatibility!.flags
                : [...(props?.compatibility?.flags ?? []), "nodejs_als"],
          },
          // Waku links SSG pages without trailing slashes; serve
          // `about/index.html` at `/about` directly instead of redirecting.
          assets: {
            htmlHandling: "drop-trailing-slash" as const,
            ...props?.assets,
          },
          main: undefined!,
          source: {
            provider: WAKU_SOURCE_PROVIDER,
            devMode: "server",
            rootDir: props?.rootDir,
            options: {
              rootDir: props?.rootDir,
              // Custom worker entry (wraps waku's handler via
              // `virtual:waku/server-entry`); resolved against `rootDir`
              // by the source provider.
              main: props?.main,
              // Deploy-time waku config overrides, merged over the
              // project's `waku.config.*` by the source provider.
              srcDir: props?.waku?.srcDir,
              distDir: props?.waku?.distDir,
              basePath: props?.waku?.basePath,
              memo: props?.memo,
            },
          },
        })),
      )) as any;