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

import { AlchemyContext } from "alchemy/AlchemyContext";
import * as Command from "alchemy/Command";
import type { Input, InputProps } from "alchemy/Input";
import * as Namespace from "alchemy/Namespace";
import * as Output from "alchemy/Output";
import { renamedFrom } from "alchemy/Rename";
import { effectClass, isYieldableEffectLike, type YieldableEffectLike } from "alchemy/Util/effect";
import { asEffect } from "alchemy/Util/types";
import * as Effect from "effect/Effect";
import { cast } from "effect/Function";
import * as Redacted from "effect/Redacted";
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";
import { isContainerDecl } from "../Workers/WorkerAsyncBindings.ts";

export interface StaticSiteProps<Bindings extends WorkerBindingProps = {}>
  extends
    Omit<WorkerProps<Bindings, WorkerAssetsConfig>, "assets" | "dev">,
    Omit<Command.BuildProps, "env"> {
  /**
   * Optional configuration for static asset routing behavior.
   * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
   */

  assets?: AssetsConfig;
  /**
   * Local dev configuration, in one of two forms.
   *
   * With `command`, `alchemy dev` skips the build and spawns `command` as a
   * long-lived child process tied to the stack's scope. Alchemy does not
   * proxy or interpret the process — the dev server's own URL (e.g.
   * `http://localhost:5173`) is what you open in the browser.
   *
   * Without `command`, `alchemy dev` runs the build and a local Worker
   * serves the output; `port`, `strictPort` and `host` configure that
   * Worker.
   *
   * @example
   * ```typescript
   * Cloudflare.Website.StaticSite("App", {
   *   command: "npm run build",
   *   outdir: "dist",
   *   main: "./src/worker.ts",
   *   dev: { command: "npm run dev" },
   * });
   * ```
   *
   * @example
   * ```typescript
   * Cloudflare.Website.StaticSite("App", {
   *   command: "npm run build",
   *   outdir: "dist",
   *   dev: { port: 4321, strictPort: true },
   * });
   * ```
   */
  dev?: StaticSiteDevCommand | StaticSiteDevWorker;
}

/**
 * `StaticSite` dev form that serves the site from an external dev server.
 */
export interface StaticSiteDevCommand {
  /**
   * Shell command to run as the local dev server (e.g. `npm run dev`).
   */
  command: string;
  /**
   * Working directory for {@link command}. Defaults to
   * {@link Command.BuildProps.cwd} (the build command's `cwd`), or
   * `process.cwd()` if neither is set.
   */
  cwd?: string;
  /**
   * Environment variables for {@link command}, merged on top of
   * `process.env`. When set, these replace the top-level `env` for the
   * dev process; otherwise the top-level `env` is passed through.
   * `Redacted` values stay out of logs and state, so put secrets here
   * rather than interpolating them into {@link command}.
   */
  env?: Record<string, string | Redacted.Redacted<string>>;
  /**
   * Override for the `url` output if alchemy fails to detect it from the stdout of the dev command
   */
  url?: string;
  port?: never;
  strictPort?: never;
  host?: never;
}

/**
 * `StaticSite` dev form that builds the site and serves it from a local
 * Worker.
 */
export interface StaticSiteDevWorker {
  /**
   * Port the local Worker listens on. If the port is unavailable, the next
   * free port is used unless {@link strictPort} is `true`.
   * @default 1337
   */
  port?: number;
  /**
   * When `true`, fail instead of falling back to another port if
   * {@link port} is already in use.
   * @default false
   */
  strictPort?: boolean;
  /**
   * Host the local Worker binds to.
   * @default "localhost"
   */
  host?: string;
  command?: never;
  cwd?: never;
  env?: never;
  url?: never;
}

type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
  [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
    Bindings,
    WorkerAssetsConfig
  >[binding];
}>;

/**
 * A Cloudflare Worker that serves static assets built by a shell command.
 *
 * `StaticSite` runs a build command (e.g. `npm run build`), content-hashes
 * the output directory, and deploys the result as a Cloudflare Worker with
 * static assets. Use this when your site has its own build step that
 * produces a directory of files — Hugo, Zola, Eleventy, or any custom
 * pipeline.
 *
 * For Vite-based projects, prefer `Cloudflare.Website.Vite` which handles
 * building automatically.
 *
 *
 * ### Basic Usage
 * Point `command` at your build script and `outdir` at where it writes
 * output. Alchemy runs the command, hashes the output, and deploys it as
 * an assets-only Worker — no Worker code is uploaded, and Cloudflare's
 * asset layer serves every request itself.
 *
 * **Example:** Deploying a Hugo site
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("Blog", {
 *   command: "hugo --minify",
 *   outdir: "public",
 * });
 * ```
 *
 * Provide `main` to put your own Worker in front of the assets instead.
 * The Worker receives an `ASSETS` binding it can delegate to:
 *
 * ```typescript
 * // src/worker.ts
 * export default {
 *   fetch: (request: Request, env: { ASSETS: Fetcher }) =>
 *     env.ASSETS.fetch(request),
 * };
 * ```
 *
 * **Example:** Custom Worker in front of the assets
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("Blog", {
 *   command: "hugo --minify",
 *   outdir: "public",
 *   main: "./src/worker.ts",
 * });
 * ```
 *
 * ### Asset Configuration
 * Use `assets` to control how Cloudflare handles routing for
 * your static files — HTML handling, not-found behavior, etc.
 *
 * **Example:** SPA-style routing
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("App", {
 *   command: "npm run build",
 *   outdir: "dist",
 *   main: "./src/worker.ts",
 *   assets: {
 *     htmlHandling: "auto-trailing-slash",
 *     notFoundHandling: "single-page-application",
 *   },
 * });
 * ```
 *
 * ### Building from a Subdirectory
 * Set `cwd` to run the build command in a subdirectory (e.g. a
 * monorepo package). `outdir` is resolved relative to `cwd`.
 *
 * **Example:** Building a frontend in a monorepo
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("Web", {
 *   cwd: "apps/web",
 *   command: "npm run build",
 *   outdir: "dist",
 *   main: "apps/web/worker.ts",
 * });
 * ```
 *
 * ### Custom Rebuild Scope
 * By default, all non-gitignored files are hashed to decide whether
 * the build should re-run. Use `memo` to narrow the scope.
 *
 * **Example:** Narrowing the memo scope
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("Docs", {
 *   command: "npm run build",
 *   outdir: "dist",
 *   main: "./src/worker.ts",
 *   memo: {
 *     include: ["content/**", "templates/**", "config.toml"],
 *   },
 * });
 * ```
 *
 * **Example:** Rebuilding when a sibling workspace package changes
 * The default scope only hashes files under `cwd` (plus the nearest
 * lockfile), so edits to a sibling workspace package the app imports do
 * not retrigger the build on their own. Add the sibling's sources with a
 * `../` include glob — and keep `lockfile: true`, since providing
 * `include` otherwise drops the lockfile from the hash:
 * ```typescript
 * const site = yield* Cloudflare.Website.StaticSite("Web", {
 *   cwd: "apps/web",
 *   command: "npm run build",
 *   outdir: "dist",
 *   main: "./src/worker.ts",
 *   memo: {
 *     include: ["**\/*", "../../packages/env/src/**"],
 *     lockfile: true,
 *   },
 * });
 * ```
 *
 * ### Class Form
 * Calling `StaticSite` 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 Blog extends Cloudflare.Website.StaticSite<Blog>()("Blog", {
 *   command: "hugo --minify",
 *   outdir: "public",
 *   main: "./src/worker.ts",
 * }) {}
 *
 * const site = yield* Blog;
 * ```
 *
 * @resource
 * @product Website
 * @category Workers & Compute
 */
export const StaticSite: {
  <Self>(): {
    <const Bindings extends WorkerBindingProps = {}, Req = never>(
      id: string,
      propsEff:
        | InputProps<StaticSiteProps<Bindings>, "dev">
        | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
    ): Effect.Effect<Self, never, Req | Providers> & {
      new (): StaticSiteWorker<Bindings>;
    };
  };
  <const Bindings extends WorkerBindingProps = {}, Req = never>(
    id: string,
    propsEff:
      | InputProps<StaticSiteProps<Bindings>, "dev">
      | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
  ): Effect.Effect<StaticSiteWorker<Bindings>, never, Req | Providers>;
} = ((id?: any, propsEff?: any) =>
  id === undefined
    ? (id: string, propsEff: any) => effectClass(makeStaticSite(id, propsEff))
    : makeStaticSite(id, propsEff)) as any;

const makeStaticSite = <const Bindings extends WorkerBindingProps = {}, Req = never>(
  id: string,
  propsEff:
    | InputProps<StaticSiteProps<Bindings>, "dev">
    | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
) =>
  Effect.gen(function* () {
    const ctx = yield* AlchemyContext;
    const props = yield* asEffect(propsEff);

    // `Dev` and `Build` carry constant logical ids, so they are namespaced
    // under `id` to keep two sites on one stack from colliding. Nothing
    // else is: the site's own `props` — and the resources its `env`
    // bindings declare — must resolve in the CALLER's namespace. Pushing
    // the namespace around the whole body instead re-declares a shared
    // resource referenced from `env` as a second copy under `<id>/`.
    // `Vite` already passes `id` straight through to `Worker`.

    // In dev mode with a dev.command, declare a DevCommand resource so
    // the sidecar owns the process lifecycle (survives user-code HMR),
    // skip the build, and tell Worker not to start a local instance.
    const devCommand = props.dev?.command !== undefined ? props.dev : undefined;
    const dev =
      ctx.dev && devCommand
        ? yield* Command.Dev("Dev", {
            command: devCommand.command,
            cwd: devCommand.cwd ?? (typeof props.cwd === "string" ? props.cwd : undefined),
            env: yield* serializeEnv(devCommand.env ?? props.env),
          }).pipe(
            Namespace.push(id),
            Effect.map((d) =>
              Output.map(d.url, (url) => ({
                url: url ?? devCommand.url,
              })),
            ),
          )
        : undefined;

    const build = dev
      ? undefined
      : yield* Command.Build("Build", {
          command: props.command,
          cwd: props.cwd,
          memo: props.memo,
          outdir: props.outdir,
          env: yield* serializeEnv(props.env),
        }).pipe(Namespace.push(id));

    // Pure-static sites (neither `main` nor `script`) deploy as
    // assets-only Workers: no script is uploaded and Cloudflare's asset
    // layer serves every request itself.
    //
    // The Worker's FQN was `<id>/Worker` before #1053 flattened it to
    // `<id>`; `renamedFrom` migrates the pre-existing state row to the new
    // FQN instead of letting the engine plan a create+delete replacement
    // (a new physical name, a torn-down workers.dev URL, and a
    // custom-domain handover that crashes the deploy).
    return yield* Worker<Bindings, WorkerAssetsConfig, Req>(id, {
      ...props,
      assets: build
        ? cast({
            directory: build.outdir,
            hash: build.hash.output,
            // oxlint-disable-next-line typescript/no-misused-spread -- assets is a plain config object in practice; a top-level Output/Effect would be dropped (pre-existing)
            ...props.assets,
          })
        : undefined,
      // Opt out of the local Worker in dev when the external DevCommand
      // is serving the content. The Worker resource still exists in
      // state with a stub Attributes shape.
      dev: dev
        ? { mode: "external", url: dev.url }
        : props.dev && !devCommand
          ? {
              port: props.dev.port,
              strictPort: props.dev.strictPort,
              host: props.dev.host,
            }
          : undefined,
      script: props.script,
    }).pipe(renamedFrom(`${id}/Worker`));
  });

/**
 * Serialize the site's `env` for the build/dev subprocess. The same record
 * doubles as the Worker's binding props, so entries may be plain strings,
 * `Redacted` secrets, `effect/Config` values, `Output` references, or
 * binding Effects:
 *
 * - strings and `Redacted` values pass through unchanged
 * - `Config` (and any other runnable Effect) is resolved here, at stack
 *   construction — passing it through unresolved would hand the subprocess
 *   the JSON-serialized `Config` object (`{"_id":"Config"}`) instead of its
 *   value (#796)
 * - `Output` references resolve at reconcile; the resolved value is
 *   serialized the same way inline values are (an `Output<object>` must
 *   reach the subprocess as JSON, not `[object Object]`)
 * - binding Effects (`~alchemy/Kind`-marked, e.g. a `WorkerLoader`) and
 *   `Cloudflare.Container` declarations have no env-var representation and
 *   are dropped
 * - remaining plain values (`null`, numbers, JSON objects) are stringified
 */
const serializeEnv = Effect.fn(function* (
  env: Input<WorkerBindingProps | Record<string, string | Redacted.Redacted<string>> | undefined>,
) {
  const entries: [string, unknown][] = [];
  for (const [k, v] of Object.entries(env ?? {})) {
    if (v === undefined) continue;
    if (typeof v === "string" || Redacted.isRedacted(v)) {
      entries.push([k, v]);
    } else if (Output.isOutput(v)) {
      entries.push([k, Output.map(v, serializeEnvValue)]);
    } else if (isContainerDecl(v)) {
      // A `Cloudflare.Container` declaration is Effect-shaped but is a
      // binding (DO namespace + ContainerApplication) — yielding it would
      // resolve the started-instance tag, which only exists inside a
      // Durable Object (#997). Deploy-time only, nothing to expose to the
      // build subprocess.
      continue;
    } else if (isYieldableEffectLike(v)) {
      const resolved = serializeEnvValue(
        yield* asEffect(v as YieldableEffectLike<unknown, unknown, never>).pipe(Effect.orDie),
      );
      if (resolved === undefined) continue;
      entries.push([k, resolved]);
    } else if (v !== null && typeof v === "object" && "~alchemy/Kind" in v) {
      // A binding Effect (e.g. WorkerLoader) — deploy-time only, nothing to
      // expose to the build subprocess.
      continue;
    } else {
      entries.push([k, JSON.stringify(v)]);
    }
  }
  return Object.fromEntries(entries) as Record<string, string | Redacted.Redacted<string>>;
});

/**
 * Serialize one resolved env value for the build/dev subprocess: strings and
 * `Redacted` pass through, everything else becomes JSON.
 */
const serializeEnvValue = (value: unknown): string | Redacted.Redacted<string> | undefined =>
  value === undefined
    ? undefined
    : typeof value === "string"
      ? value
      : Redacted.isRedacted(value)
        ? (value as Redacted.Redacted<string>)
        : JSON.stringify(value);