alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Cloudflare/Website/Astro.ts

@@ -57,33 +57,40 @@ export interface AstroProps<
    */
   prerenderEnvironment?: "workerd" | "node";
   /**
-   * Serializable Astro config merged into the in-memory configuration.
-   * The project's `astro.config.*` file loads natively; astro merges
-   * these options OVER it (scalars override the file). The Cloudflare
-   * adapter, output target, and Vite environments are managed for you —
-   * do not declare an `adapter` in the config file.
+   * Deploy-time Astro config overrides, merged OVER your natively-loaded
+   * `astro.config.*` (values here win). Use it for values that vary per
+   * stage or derive from other resources' Outputs — everything else
+   * belongs in the config file.
    */
   astro?: {
-    /** The full URL the site deploys to (`Astro.site`). */
+    /** Deployed URL origin (astro's `site`). */
     site?: string;
-    /** Base path the site deploys under. */
+    /** Base path the site is served from (astro's `base`). */
     base?: string;
     /**
-     * Astro output target. `"server"` renders pages on demand in the
-     * Worker; individual pages opt into prerendering with
-     * `export const prerender = true`.
+     * Astro output target — a deploy-topology decision (whether Worker
+     * code runs at request time). `"server"` renders pages on demand in
+     * the Worker; individual pages opt into prerendering with
+     * `export const prerender = true`. `"static"` prerenders every page
+     * at build time and deploys assets-only. Supersedes a file-level
+     * `output`.
      * @default "server"
      */
     output?: "server" | "static";
-    /** Source directory, relative to `rootDir`. @default "./src" */
+    /** Source directory (astro's `srcDir`). */
     srcDir?: string;
-    /** Public (static passthrough) directory. @default "./public" */
+    /** Public assets directory (astro's `publicDir`). */
     publicDir?: string;
-    /** Build output directory. @default "./dist" */
+    /** Build output directory (astro's `outDir`). */
     outDir?: string;
-    /** Trailing-slash handling for routes. */
+    /** Trailing-slash handling (astro's `trailingSlash`). */
     trailingSlash?: "always" | "never" | "ignore";
   };
+  /**
+   * Path to an alternate astro config file, relative to `rootDir`.
+   * Defaults to astro's own config discovery.
+   */
+  config?: string;
   /**
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
@@ -127,16 +134,18 @@ export interface AstroProps<
  * ### Static Sites
  * With `astro: { output: "static" }` every page is prerendered at build
  * time and the deploy is **assets-only**: no server bundle is uploaded —
- * Cloudflare's asset layer answers every request (including the built
- * `404.html` via `assets.notFoundHandling: "404-page"`). Session
- * provisioning is skipped for declared-static sites since no Worker code
- * runs at request time.
+ * Cloudflare's asset layer answers every request (serve the built
+ * `404.html` via `assets: { notFoundHandling: "404-page" }`). Session
+ * provisioning is skipped for declared-static sites since no Worker
+ * code runs at request time.
  *
  * **Example:** Fully static Astro site
  * ```typescript
  * const site = yield* Cloudflare.Website.Astro("Docs", {
  *   astro: { output: "static" },
- *   assets: { notFoundHandling: "404-page" },
+ *   assets: {
+ *     notFoundHandling: "404-page",
+ *   },
  * });
  * ```
  *
@@ -198,23 +207,22 @@ export interface AstroProps<
  * ```
  *
  * ### Astro Configuration
- * Your `astro.config.*` file loads natively — integrations, Vite
- * plugins, and other non-serializable options work as usual. Common
- * serializable options are exposed under `astro` for deploy-specific
- * overrides; astro merges them OVER the config file (scalars override,
- * arrays like `integrations` concatenate). The Cloudflare adapter is
- * injected for you — declaring an `adapter` in the config file fails
- * the build. `output` defaults to `"server"`, superseding a file-level
- * `output`; opt into a fully prerendered site with
- * `astro: { output: "static" }`.
+ * Your `astro.config.*` is the home for Astro configuration
+ * (integrations, Vite plugins, `site`, `base`, ...) and loads natively.
+ * The Cloudflare adapter is injected for you — declaring an `adapter`
+ * in the config file fails the build. The `astro` prop is a
+ * deploy-time override bag merged OVER the file (values here win) for
+ * settings that vary per stage or derive from other resources'
+ * Outputs, which a config file cannot consume. `output` defaults to
+ * `"server"` — astro's zero-config `"static"` default would prerender
+ * every page inside workerd, where the Worker's bindings don't exist.
+ * Use `config` to point at an alternate config file (relative to
+ * `rootDir`).
  *
- * **Example:** Setting the site URL and source directory
+ * **Example:** Per-stage site URL override
  * ```typescript
  * const site = yield* Cloudflare.Website.Astro("Blog", {
- *   astro: {
- *     site: "https://blog.example.com",
- *     srcDir: "./app",
- *   },
+ *   astro: { site: "https://blog.example.com" },
  * });
  * ```
  *
@@ -311,14 +319,17 @@ export const Astro: {
                 // opt-out.
                 sessionKVBindingName: props.sessionKVBindingName,
                 prerenderEnvironment: props.prerenderEnvironment,
-                // Server output is the documented default: astro's own
-                // zero-config default is `"static"`, which would prerender
-                // every page at build time inside workerd — where the
-                // Worker's bindings don't exist. The inline config merges
-                // OVER a project's `astro.config.*`, so an explicit
-                // file-level `output` is superseded; opt into a fully
-                // prerendered site with `astro: { output: "static" }`.
-                astro: { output: "server", ...props.astro },
+                // The `astro` bag is the deploy-time overlay merged OVER
+                // the natively-loaded `astro.config.*`. Server output is
+                // the documented default: astro's own zero-config default
+                // is `"static"`, which would prerender every page at
+                // build time inside workerd — where the Worker's bindings
+                // don't exist.
+                astro: {
+                  ...props.astro,
+                  output: props.astro?.output ?? "server",
+                },
+                config: props.config,
               },
             },
           };

package/src/Cloudflare/Website/Foldkit.ts

@@ -69,7 +69,7 @@ export interface FoldkitProps<
    * Foldkit apps route on the client, so `notFoundHandling` defaults to
    * `"single-page-application"` — unmatched paths serve `index.html` and
    * the app's router takes over. Set `notFoundHandling` explicitly to
-   * override.
+   * override (e.g. `"404-page"` to serve the built `404.html`).
    *
    * @default { notFoundHandling: "single-page-application" }
    */
@@ -111,9 +111,8 @@ export interface FoldkitProps<
  *
  * ### Single-Page Application Routing
  * Unmatched paths serve `index.html` by default so deep links boot the
- * app and the Foldkit router resolves the route. An explicit `assets`
- * config merges over the default — a site that ships real 404 content
- * can opt out.
+ * app and the Foldkit router resolves the route. A site that ships real
+ * 404 content overrides the default with `notFoundHandling: "404-page"`.
  *
  * **Example:** Serving a real 404 page
  * ```typescript
@@ -215,7 +214,8 @@ export const Foldkit: {
           (props) => ({
             ...props,
             // Foldkit routes on the client; serve index.html for unmatched
-            // paths so deep links boot the app instead of 404ing.
+            // paths so deep links boot the app instead of 404ing. An
+            // explicit `assets.notFoundHandling` wins over the default.
             assets: {
               notFoundHandling: "single-page-application" as const,
               ...props?.assets,

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",
  *   },
  * });