alchemy 2.0.0-beta.74 → 2.0.0-beta.75

package/src/Cloudflare/Website/Nextjs.ts

@@ -28,55 +28,11 @@ const NEXTJS_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/nextjs/source";
  */
 const DEFAULT_COMPATIBILITY_DATE = "2026-05-12";
 
-/** Next.js/OpenNext-specific build knobs, forwarded to the source provider. */
-export interface NextjsBuildOptions {
-  /**
-   * Path of the OpenNext config, relative to the project root.
-   * @default "open-next.config.ts"
-   */
-  configPath?: string;
-  /**
-   * The command the OpenNext pipeline runs to build the Next.js app.
-   * A `buildCommand` set in the project's `open-next.config.ts` takes
-   * precedence over this option.
-   * @default "npx next build"
-   */
-  buildCommand?: string;
-  /**
-   * Skip the internal `next build` and reuse an existing `.next` directory.
-   * @default false
-   */
-  skipNextBuild?: boolean;
-  /**
-   * Minify the OpenNext bundling steps and the final worker bundle pass.
-   * @default false
-   */
-  minify?: boolean;
-  /**
-   * Enable OpenNext debug logging (and verbose workerd output in dev).
-   * @default false
-   */
-  debug?: boolean;
-  /**
-   * Local dev (`alchemy dev`) behavior.
-   *
-   * - `"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"
-   */
-  devMode?: "preview" | "hmr";
-}
-
 export interface NextjsProps<
   Bindings extends WorkerBindingProps = {},
 > extends Omit<
   WorkerProps<Bindings>,
-  "vite" | "main" | "assets" | "script" | "bundle" | "source" | "rules"
+  "vite" | "main" | "assets" | "script" | "bundle" | "source" | "rules" | "dev"
 > {
   /**
    * The Next.js project root (the directory containing `next.config.*` and
@@ -91,8 +47,29 @@ export interface NextjsProps<
    * `include`/`exclude` globs when the default is too broad.
    */
   memo?: MemoOptions;
-  /** Next.js/OpenNext-specific build and dev configuration. */
-  nextjs?: NextjsBuildOptions;
+  // The OpenNext build pipeline (buildCommand, minify, debug, ...) is
+  // configured in YOUR `open-next.config.ts`, which OpenNext loads
+  // natively — this resource only deploys the result.
+  /**
+   * 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`
@@ -119,8 +96,8 @@ export interface NextjsProps<
  * `import()`.
  *
  * Local dev (`alchemy dev`) defaults to preview parity — the built worker
- * served under workerd. Set `nextjs: { devMode: "hmr" }` for the real
- * `next dev` (Turbopack HMR) with the Worker's bindings proxied onto
+ * served under workerd. Set `devMode: "hmr"` for the real `next dev`
+ * (Turbopack HMR) with the Worker's bindings proxied onto
  * `getCloudflareContext()`.
  *
  * ISR comes in two flavors, chosen by the project's `open-next.config.ts`:
@@ -248,18 +225,9 @@ export interface NextjsProps<
  * ```
  *
  * ### Build Configuration
- * The `nextjs` prop tunes the OpenNext pipeline: a custom build command,
- * minification, or reusing an existing `.next` build.
- *
- * **Example:** Minified build with a custom command
- * ```typescript
- * const site = yield* Cloudflare.Website.Nextjs("Site", {
- *   nextjs: {
- *     buildCommand: "npx next build --no-lint",
- *     minify: true,
- *   },
- * });
- * ```
+ * The OpenNext build pipeline (build command, minification, ...) is
+ * configured in your project's `open-next.config.ts`, which loads
+ * natively — the resource only deploys the result.
  *
  * ### Class Form
  * Calling `Nextjs` with no arguments returns a constructor you can
@@ -318,6 +286,13 @@ export const Nextjs: {
           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
@@ -356,13 +331,8 @@ export const Nextjs: {
               options: {
                 root: props?.rootDir,
                 memo: props?.memo,
-                ...(props?.nextjs !== undefined
-                  ? (({ devMode, ...build }) => ({
-                      ...build,
-                      ...(devMode !== undefined
-                        ? { dev: { mode: devMode } }
-                        : {}),
-                    }))(props.nextjs)
+                ...(props?.dev?.mode !== undefined
+                  ? { dev: { mode: props.dev.mode } }
                   : {}),
               },
             },

package/src/Cloudflare/Website/Nuxt.ts

@@ -57,21 +57,24 @@ export interface NuxtProps<
    * `include`/`exclude` globs when the project sits in a large repository.
    */
   memo?: MemoOptions;
-  /**
-   * Nuxt configuration overrides merged over the project's own
-   * `nuxt.config.ts` (the override wins). The project's config file is
-   * loaded natively — modules, layers, and all — so this is for
-   * deploy-specific tweaks (`routeRules`, `runtimeConfig`, ...). Must be
-   * JSON-serializable (it persists in state). Do not set `nitro.preset`
-   * here — the Cloudflare deploy target owns the preset and a foreign
-   * preset is a hard error.
-   */
-  nuxt?: Record<string, unknown>;
   /**
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
    */
   assets?: AssetsConfig;
+  /**
+   * Nuxt config overrides merged over the project's own `nuxt.config.ts`
+   * (the highest-priority c12 layer — a value here wins over the file).
+   * Use it for deploy-time values the config file can't express, e.g.
+   * per-stage `runtimeConfig`; `nuxt.config.ts` remains the primary home
+   * for everything else.
+   *
+   * Must be JSON-serializable — no functions, plugins, or modules (the
+   * value persists in state and participates in the rebuild hash).
+   * `nitro.preset` is always owned by the deploy target and cannot be
+   * overridden here.
+   */
+  nuxt?: Record<string, unknown>;
 }
 
 /**
@@ -155,14 +158,34 @@ export interface NuxtProps<
  * ### Prerendering
  * Routes marked for prerendering in `routeRules` (or via
  * `nitro.prerender`) render at build time into `.output/public` and are
- * served as static assets — no Worker invocation.
+ * served as static assets — no Worker invocation. Configure them in
+ * your `nuxt.config.ts`, which loads natively:
+ *
+ * **Example:** Prerendering a route (nuxt.config.ts)
+ * ```typescript
+ * // nuxt.config.ts
+ * export default defineNuxtConfig({
+ *   routeRules: {
+ *     "/about": { prerender: true },
+ *   },
+ * });
+ * ```
+ *
+ * ### Config Overrides
+ * `nuxt.config.ts` is the primary home for Nuxt configuration — it loads
+ * natively. The `nuxt` prop layers deploy-time overrides on top (the
+ * highest-priority c12 layer) for values the file can't express, like
+ * per-stage settings. The bag must be JSON-serializable — no functions,
+ * plugins, or modules — and `nitro.preset` stays owned by the deploy
+ * target.
  *
- * **Example:** Prerendering a route
+ * **Example:** Deploy-time config overrides
  * ```typescript
  * const site = yield* Cloudflare.Website.Nuxt("Website", {
  *   nuxt: {
- *     routeRules: {
- *       "/about": { prerender: true },
+ *     app: { baseURL: "/docs/" },
+ *     runtimeConfig: {
+ *       public: { apiBase: "https://api.example.com" },
  *     },
  *   },
  * });

package/src/Cloudflare/Website/SvelteKit.ts

@@ -33,41 +33,14 @@ export interface SvelteKitProps<
    */
   memo?: MemoOptions;
   /**
-   * SvelteKit configuration overrides. A project-owned `vite.config.*`
-   * loads natively — its `sveltekit(...)` call is the primary config
-   * source — and these options are merged OVER it (the override wins).
-   * Without a config file, this is the whole kit config. Construction-time
-   * options (`preprocess`, `extensions`, `compilerOptions`, `vitePlugin`)
-   * only apply in the no-config-file case — put them in your own
-   * `sveltekit(...)` call otherwise. The `adapter` field is injected by
-   * Alchemy's wrangler-free Cloudflare adapter — do not set it here. Must
-   * be JSON-serializable (it persists in state).
+   * SvelteKit config overrides for the `sveltekit(...)` plugin call, merged
+   * over the options of the user's own call (these win). JSON-serializable
+   * only — no `preprocess`/`vitePlugin`/functions; construction-time options
+   * (`preprocess`, `extensions`, `compilerOptions`, `vitePlugin`) can only
+   * apply when no user `vite.config.*` exists. The `adapter` field is
+   * always owned by alchemy.
    */
   kit?: Record<string, unknown>;
-  /**
-   * Options for the wrangler-free Cloudflare adapter.
-   */
-  adapter?: {
-    /**
-     * Name of the static-assets binding the generated worker serves files
-     * through.
-     * @default "ASSETS"
-     */
-    assetsBinding?: string;
-    /**
-     * Fallback-page generation, mirroring Workers static assets
-     * `not_found_handling`: `"404-page"` writes a `404.html`,
-     * `"single-page-application"` writes an app-shell `index.html`.
-     * @default "none"
-     */
-    notFoundHandling?: "none" | "404-page" | "single-page-application";
-    /**
-     * With `notFoundHandling: "404-page"`: `"spa"` renders the app shell
-     * as the fallback, `"plaintext"` writes a plain `Not Found` page.
-     * @default "plaintext"
-     */
-    fallback?: "spa" | "plaintext";
-  };
   /**
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
@@ -131,18 +104,31 @@ export interface SvelteKitProps<
  * // });
  * ```
  *
- * ### Kit and Adapter Options
- * Kit options normally live in the `sveltekit(...)` call in your
- * `vite.config.ts`, which loads natively; `kit` is a deploy-time
- * override layer merged over them (the override wins). The generated
- * Cloudflare adapter is configured via `adapter`.
+ * ### Kit Options and 404 Handling
+ * Kit options live in the `sveltekit(...)` call in your
+ * `vite.config.ts`, which loads natively. Fallback-page behavior is
+ * driven by the platform-native `assets.notFoundHandling` knob — the
+ * build generates the matching fallback page (rendering the app shell,
+ * so kit's own error page shows).
  *
- * **Example:** SPA-style 404 fallback
+ * **Example:** App-shell 404 fallback
  * ```typescript
  * const site = yield* Cloudflare.Website.SvelteKit("Website", {
- *   adapter: {
+ *   assets: {
  *     notFoundHandling: "404-page",
- *     fallback: "spa",
+ *   },
+ * });
+ * ```
+ *
+ * The `kit` prop is a deploy-time override bag merged over your own
+ * `sveltekit(...)` options (the prop wins) — useful for per-stage values
+ * the config file can't compute. JSON-serializable values only.
+ *
+ * **Example:** Deploy-time kit overrides
+ * ```typescript
+ * const site = yield* Cloudflare.Website.SvelteKit("Website", {
+ *   kit: {
+ *     paths: { base: "/docs" },
  *   },
  * });
  * ```
@@ -221,22 +207,7 @@ export const SvelteKit: {
             // SvelteKit's server graph is built for Node and needs
             // `nodejs_compat` — `getCompatibility` already adds it to every
             // non-python Worker.
-            // The adapter's `notFoundHandling` generates the fallback pages
-            // and the worker shim's 404 deferral, but the Workers assets
-            // layer has its own `not_found_handling` knob — if they
-            // disagree, unknown routes come back as empty-body 404s (the
-            // shim defers to an assets layer still on "none"). Default the
-            // assets-layer knob from the adapter so one prop configures the
-            // whole story; an explicit `assets.notFoundHandling` wins.
-            assets:
-              props?.adapter?.notFoundHandling !== undefined &&
-              props.adapter.notFoundHandling !== "none" &&
-              props.assets?.notFoundHandling === undefined
-                ? {
-                    ...props.assets,
-                    notFoundHandling: props.adapter.notFoundHandling,
-                  }
-                : props?.assets,
+            assets: props?.assets,
             source: {
               provider: "@alchemy.run/frontend-frameworks/sveltekit/source",
               devMode: "server",
@@ -245,7 +216,21 @@ export const SvelteKit: {
                 rootDir: props?.rootDir,
                 memo: props?.memo,
                 kit: props?.kit,
-                adapter: props?.adapter,
+                // The adapter's build-time page GENERATION (404.html /
+                // app-shell index.html) is derived from the one
+                // platform-native knob, `assets.notFoundHandling`, so a
+                // single prop configures generation AND serving — the two
+                // halves can never disagree. The generated 404-page
+                // renders the app shell so kit's own error page shows.
+                ...(props?.assets?.notFoundHandling !== undefined &&
+                props.assets.notFoundHandling !== "none"
+                  ? {
+                      adapter: {
+                        notFoundHandling: props.assets.notFoundHandling,
+                        fallback: "spa",
+                      },
+                    }
+                  : {}),
               },
             },
           }),

package/src/Cloudflare/Website/Vite.ts

@@ -110,14 +110,13 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * ```
  *
  * ### Single-Page Applications
- * For SPAs (React, Vue, etc.), configure asset handling so all
- * routes fall back to `index.html`.
+ * For SPAs (React, Vue, etc.), configure asset handling so unmatched
+ * routes fall back to `index.html` and the client router takes over.
  *
  * **Example:** Vue SPA
  * ```typescript
  * const app = yield* Cloudflare.Website.Vite("Vue", {
  *   assets: {
- *     htmlHandling: "auto-trailing-slash",
  *     notFoundHandling: "single-page-application",
  *   },
  * });

package/src/Cloudflare/Website/Vocs.ts

@@ -0,0 +1,195 @@
+import * as Effect from "effect/Effect";
+import type { MemoOptions } from "../../Command/Memo.ts";
+import type { InputProps } from "../../Input.ts";
+import { effectClass } from "../../Util/effect.ts";
+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";
+
+const VOCS_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/vocs/source";
+
+export interface VocsProps<
+  Bindings extends WorkerBindingProps = {},
+> extends Omit<
+  WorkerProps<Bindings>,
+  "vite" | "main" | "assets" | "source" | "script" | "bundle"
+> {
+  /**
+   * Root directory of the Vocs project.
+   * @default process.cwd()
+   */
+  rootDir?: string;
+  /**
+   * Vocs build output directory, relative to {@link rootDir}. Set this when
+   * `vocs.config.*` customizes `outDir` so generated output stays outside the
+   * rebuild hash.
+   * @default "dist"
+   */
+  outDir?: string;
+  /**
+   * Controls which files feed the content hash that decides whether Vocs
+   * rebuilds. By default every non-gitignored file under {@link rootDir} is
+   * hashed, plus the nearest package-manager lockfile.
+   */
+  memo?: MemoOptions;
+  /**
+   * Static asset routing configuration. Vocs links prerendered pages without
+   * trailing slashes, so extensionless routing is enabled by default.
+   * @default { htmlHandling: "drop-trailing-slash" }
+   */
+  assets?: AssetsConfig;
+}
+
+/**
+ * A Cloudflare Worker deployed from a [Vocs](https://vocs.dev) documentation project.
+ *
+ * Vocs' `vocs.config.*` loads natively. Alchemy runs Vocs' Waku/RSC build,
+ * deploys its server environments as a Worker, and publishes the client and
+ * prerendered output as static assets. No Vite or Wrangler config is required.
+ *
+ * Requires `@alchemy.run/frontend-frameworks`, `vocs`, and Vocs' Waku peer
+ * dependencies in the project.
+ *
+ * Input files are content-hashed (respecting `.gitignore` by default), so an
+ * unchanged project skips its build and deployment. Vocs' server runtime uses
+ * Node APIs, so `nodejs_compat` is included in the Worker's compatibility
+ * flags automatically.
+ *
+ * ### Deploying a Vocs Site
+ * A single resource builds the documentation project and deploys its server
+ * runtime, prerendered pages, generated files, and public assets.
+ *
+ * **Example:** Vocs documentation site
+ * ```typescript
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ * });
+ * ```
+ *
+ * ### Bindings
+ * Pass Cloudflare resources through `env` like any other Worker. Server-side
+ * Vocs and MDX code can access them from `cloudflare:workers`.
+ *
+ * **Example:** Vocs with a KV namespace
+ * ```typescript
+ * const searchCache = yield* Cloudflare.KV.Namespace("SearchCache");
+ *
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   env: {
+ *     SEARCH_CACHE: searchCache,
+ *   },
+ * });
+ * ```
+ *
+ * ### Custom Build Output
+ * Vocs configuration continues to own the output directory. When
+ * `vocs.config.*` changes `outDir`, mirror that value on the resource so the
+ * generated directory is excluded from the rebuild hash and read correctly.
+ *
+ * **Example:** Custom output directory
+ * ```typescript
+ * // vocs.config.ts: defineConfig({ outDir: "build" })
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   outDir: "build",
+ * });
+ * ```
+ *
+ * ### Custom Rebuild Scope
+ * Use `memo` to narrow the files that trigger a rebuild in large projects.
+ *
+ * **Example:** Narrowing the memo scope
+ * ```typescript
+ * const docs = yield* Cloudflare.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   memo: {
+ *     include: ["src/**", "public/**", "vocs.config.ts", "package.json"],
+ *   },
+ * });
+ * ```
+ *
+ * ### Class Form
+ * Calling `Vocs` without arguments returns a constructor for declaring the
+ * deployed Worker as a named class.
+ *
+ * **Example:** Declaring a Vocs Worker class
+ * ```typescript
+ * class Docs extends Cloudflare.Website.Vocs<Docs>()("Docs", {
+ *   rootDir: "./docs",
+ * }) {}
+ *
+ * const docs = yield* Docs;
+ * ```
+ *
+ * @resource
+ * @product Website
+ * @category Workers & Compute
+ */
+export const Vocs: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff?:
+        | InputProps<VocsProps<Bindings>>
+        | Effect.Effect<InputProps<VocsProps<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?:
+      | InputProps<VocsProps<Bindings>>
+      | Effect.Effect<InputProps<VocsProps<Bindings>>, never, Req>,
+  ): Effect.Effect<
+    Worker<{
+      [
+        binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>
+      ]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+    }>,
+    never,
+    Req | Providers
+  >;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(Vocs(id, propsEff))
+    : Worker(
+        id,
+        Effect.map(
+          Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
+          (props) => ({
+            ...props,
+            compatibility: {
+              ...props?.compatibility,
+              flags: props?.compatibility?.flags?.includes("nodejs_compat")
+                ? props.compatibility.flags
+                : [...(props?.compatibility?.flags ?? []), "nodejs_compat"],
+            },
+            assets: {
+              htmlHandling: "drop-trailing-slash" as const,
+              ...props?.assets,
+            },
+            main: undefined!,
+            source: {
+              provider: VOCS_SOURCE_PROVIDER,
+              devMode: "server",
+              options: {
+                rootDir: props?.rootDir,
+                outDir: props?.outDir,
+                memo: props?.memo,
+              },
+            },
+          }),
+        ),
+      )) as any;

package/src/Cloudflare/Website/Waku.ts

@@ -50,28 +50,6 @@ export interface WakuProps<
    * directory.
    */
   rootDir?: string;
-  /**
-   * Waku source directory, relative to {@link rootDir}. Setting this
-   * overrides a `srcDir` in the project's `waku.config.*`.
-   * @default the project's `waku.config.*` value, or waku's own default (`"src"`)
-   */
-  srcDir?: string;
-  /**
-   * Waku build output directory, relative to {@link rootDir}. The server
-   * bundle is read from `<distDir>/server` and the client assets from
-   * `<distDir>/public`. Setting this overrides a `distDir` in the
-   * project's `waku.config.*` — if your config file customizes `distDir`,
-   * mirror it here (or exclude it via `memo`) so the build output doesn't
-   * pollute the rebuild hash.
-   * @default the project's `waku.config.*` value, or waku's own default (`"dist"`)
-   */
-  distDir?: string;
-  /**
-   * Base path the app is served under. Setting this overrides a
-   * `basePath` in the project's `waku.config.*`.
-   * @default the project's `waku.config.*` value, or waku's own default (`"/"`)
-   */
-  basePath?: string;
   /**
    * Controls which files feed the content hash that decides whether a
    * rebuild is needed. By default every non-gitignored file under
@@ -91,6 +69,31 @@ export interface WakuProps<
    * @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;
+  };
 }
 
 /**
@@ -98,8 +101,9 @@ export interface WakuProps<
  *
  * `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) as the base config,
- * with `srcDir`/`distDir`/`basePath` from this resource winning per key;
+ * `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
@@ -135,6 +139,20 @@ export interface WakuProps<
  * });
  * ```
  *
+ * ### 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
@@ -274,9 +292,11 @@ export const Waku: {
                 // `virtual:waku/server-entry`); resolved against `rootDir`
                 // by the source provider.
                 main: props?.main,
-                srcDir: props?.srcDir,
-                distDir: props?.distDir,
-                basePath: props?.basePath,
+                // 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,
               },
             },

package/src/Cloudflare/Website/index.ts

@@ -6,4 +6,5 @@ export * from "./Octane.ts";
 export * from "./StaticSite.ts";
 export * from "./SvelteKit.ts";
 export * from "./Vite.ts";
+export * from "./Vocs.ts";
 export * from "./Waku.ts";