alchemy 2.0.0-beta.65 → 2.0.0-beta.66

package/src/Cloudflare/R2/BucketLocal.ts

@@ -2,26 +2,35 @@ import * as Effect from "effect/Effect";
 import type * as HttpClient from "effect/unstable/http/HttpClient";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import type { Credentials } from "../Credentials.ts";
+import { dispatchByMode } from "../LocalGateway.ts";
 import type { Bucket } from "./Bucket.ts";
+import type { makeHelpers } from "./BucketBinding.ts";
 import type { R2Auth } from "./BucketHttp.ts";
+import { makeProxyBucketHelpers } from "./LocalR2Gateway.ts";
 
 /**
  * Shared scaffolding for the R2 `*Local` binding layers.
  *
  * Resolves the account + captures the ambient current-credentials context at
- * layer construction, then returns the deferred binding callable. The callable
- * reads the bucket name/jurisdiction as deferred accessors (resolved at apply
- * time) and builds the same HTTP-backed client the `*Http` variant uses, but
- * authorized with the current CLI credentials instead of a minted token.
+ * layer construction, then returns the deferred binding callable. The
+ * callable reads the bucket name/jurisdiction as deferred accessors
+ * (resolved at apply time) and builds the client per resolved name:
+ *
+ * - a REAL name gets the HTTP client (same builders as the `*Http` variant,
+ *   authorized with the current CLI credentials — no minted token);
+ * - a `dev:` name (local emulation under `alchemy dev`) gets the native
+ *   binding client (same builders as the `*Binding` variant) over a scoped
+ *   platform-proxy gateway (see `LocalR2Gateway.ts`).
  *
  * NOT exported from `index.ts`.
  */
-export const makeLocalBucketBinding = <Client>(makeClient: {
-  (
+export const makeLocalBucketBinding = <Client extends object>(options: {
+  makeHttpClient: (
     auth: R2Auth,
     bucketName: Effect.Effect<string>,
     jurisdiction: Effect.Effect<string>,
-  ): Client;
+  ) => Client;
+  makeNativeClient: (helpers: ReturnType<typeof makeHelpers>) => Client;
 }) =>
   Effect.gen(function* () {
     // Account + credentials are ambient during stack-eval (the stack's
@@ -31,6 +40,11 @@ export const makeLocalBucketBinding = <Client>(makeClient: {
     const context = yield* Effect.context<
       Credentials | HttpClient.HttpClient
     >();
+    // The FULL ambient context, for the dev-mode gateway: booting an
+    // ephemeral workerd needs the platform services and the Cloudflare
+    // environment, all present during stack-eval but not statically
+    // enumerable here.
+    const ambient = yield* Effect.context<never>();
 
     const auth: R2Auth = {
       authorize: (eff) => eff.pipe(Effect.provideContext(context)),
@@ -42,6 +56,9 @@ export const makeLocalBucketBinding = <Client>(makeClient: {
       // `host.bind`: the local variant registers no binding.
       const bucketName = yield* bucket.bucketName;
       const jurisdiction = yield* bucket.jurisdiction;
-      return makeClient(auth, bucketName, jurisdiction);
+      const httpClient = options.makeHttpClient(auth, bucketName, jurisdiction);
+      return dispatchByMode(bucketName, httpClient, (name) =>
+        options.makeNativeClient(makeProxyBucketHelpers(name, ambient)),
+      );
     });
   });

package/src/Cloudflare/R2/LocalR2Gateway.ts

@@ -0,0 +1,84 @@
+/**
+ * Node-side path into the local workerd R2 simulator, built on the
+ * runtime's platform proxy (`PlatformProxy.open` — our `getPlatformProxy`).
+ *
+ * For a `dev:` bucket there is no cloud bucket to speak REST to. Instead,
+ * each operation opens a scoped platform proxy hosting the native R2
+ * binding and runs against `proxy.env.R2` — the proxy protocol rehydrates
+ * `R2Object`/`R2ObjectBody` on the Node side, matching the surface the
+ * Worker-binding client builders (`makeRead` / `makeWrite`) consume, so the
+ * `*Local` layers reuse those builders verbatim:
+ *
+ *   Node ── proxy.env.R2.get(...) ──▶ r2 service ──▶ R2BucketObject
+ *
+ * One proxy boot per operation — slow but correct; the `*Local` layers run
+ * in deploy-time Actions, not on a request path. Data lands in the same
+ * `{storage}/r2` directory every local worker binding reads.
+ *
+ * NOT exported from `index.ts` — capability-internal scaffolding.
+ */
+import { R2Bucket } from "@distilled.cloud/cloudflare-runtime/bindings";
+import { open } from "@distilled.cloud/cloudflare-runtime/platform-proxy";
+import type * as runtime from "@cloudflare/workers-types";
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { gatewayName, localGatewayRuntime } from "../LocalGateway.ts";
+import { makeR2ObjectWrappers, type makeHelpers } from "./BucketBinding.ts";
+import { R2Error } from "./BucketTypes.ts";
+
+const tryPromise = <T>(fn: () => Promise<T>): Effect.Effect<T, R2Error> =>
+  Effect.tryPromise({
+    try: fn,
+    catch: (error: any) =>
+      new R2Error({
+        message: error?.message ?? "Unknown error",
+        cause: error,
+      }),
+  });
+
+/**
+ * Binding-client helpers backed by a per-operation platform proxy instead
+ * of a Worker's `env`. `raw` cannot be satisfied — a native bucket only
+ * lives as long as its proxy's scope — so it dies with guidance.
+ */
+export const makeProxyBucketHelpers = (
+  bucketName: string,
+  /**
+   * The FULL ambient stack-eval context: platform services for booting
+   * workerd plus `CloudflareEnvironment`/`AlchemyContext` for the runtime
+   * layer.
+   */
+  ambient: Context.Context<never>,
+): ReturnType<typeof makeHelpers> => {
+  const use = <T>(
+    fn: (raw: runtime.R2Bucket) => Promise<T>,
+  ): Effect.Effect<T, R2Error> =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const proxy = yield* open({
+          name: gatewayName("alchemy-r2-gateway", bucketName),
+          bindings: [R2Bucket.local({ binding: "R2", id: bucketName })],
+        });
+        const bucket = (proxy.env as Record<string, unknown>)
+          .R2 as runtime.R2Bucket;
+        return yield* tryPromise(() => fn(bucket));
+      }),
+    ).pipe(
+      Effect.provide(localGatewayRuntime),
+      // The gateway layer's platform requirements are satisfied by the
+      // ambient stack-eval context; `Context<never>` can't prove that
+      // statically, so erase the leftover R (and the proxy's own infra
+      // error channel) with a cast — mirroring D1's gateway.
+      Effect.provideContext(ambient),
+    ) as Effect.Effect<T, R2Error>;
+
+  const raw = Effect.die(
+    new R2Error({
+      message:
+        "A locally-emulated R2 bucket has no long-lived native binding outside a Worker; use put/get/head/list/delete (each runs through a scoped local gateway).",
+      cause: new Error("unsupported"),
+    }),
+  ) as Effect.Effect<runtime.R2Bucket>;
+
+  return { raw, use, tryPromise, ...makeR2ObjectWrappers(tryPromise) };
+};

package/src/Cloudflare/R2/ReadBucketLocal.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { makeLocalBucketBinding } from "./BucketLocal.ts";
+import { makeRead } from "./ReadBucketBinding.ts";
 import { ReadBucket } from "./ReadBucket.ts";
 import { makeReadR2HttpClient } from "./ReadBucketHttp.ts";
 
@@ -29,5 +30,10 @@ import { makeReadR2HttpClient } from "./ReadBucketHttp.ts";
  */
 export const ReadBucketLocal = Layer.effect(
   ReadBucket,
-  Effect.suspend(() => makeLocalBucketBinding(makeReadR2HttpClient)),
+  Effect.suspend(() =>
+    makeLocalBucketBinding({
+      makeHttpClient: makeReadR2HttpClient,
+      makeNativeClient: makeRead,
+    }),
+  ),
 );

package/src/Cloudflare/R2/ReadWriteBucketLocal.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { makeLocalBucketBinding } from "./BucketLocal.ts";
+import { makeReadWrite } from "./ReadWriteBucketBinding.ts";
 import { ReadWriteBucket } from "./ReadWriteBucket.ts";
 import { makeReadWriteR2HttpClient } from "./ReadWriteBucketHttp.ts";
 
@@ -32,5 +33,10 @@ import { makeReadWriteR2HttpClient } from "./ReadWriteBucketHttp.ts";
  */
 export const ReadWriteBucketLocal = Layer.effect(
   ReadWriteBucket,
-  Effect.suspend(() => makeLocalBucketBinding(makeReadWriteR2HttpClient)),
+  Effect.suspend(() =>
+    makeLocalBucketBinding({
+      makeHttpClient: makeReadWriteR2HttpClient,
+      makeNativeClient: makeReadWrite,
+    }),
+  ),
 );

package/src/Cloudflare/R2/WriteBucketLocal.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import { makeLocalBucketBinding } from "./BucketLocal.ts";
+import { makeWrite } from "./WriteBucketBinding.ts";
 import { WriteBucket } from "./WriteBucket.ts";
 import { makeWriteR2HttpClient } from "./WriteBucketHttp.ts";
 
@@ -29,5 +30,10 @@ import { makeWriteR2HttpClient } from "./WriteBucketHttp.ts";
  */
 export const WriteBucketLocal = Layer.effect(
   WriteBucket,
-  Effect.suspend(() => makeLocalBucketBinding(makeWriteR2HttpClient)),
+  Effect.suspend(() =>
+    makeLocalBucketBinding({
+      makeHttpClient: makeWriteR2HttpClient,
+      makeNativeClient: makeWrite,
+    }),
+  ),
 );

package/src/Cloudflare/Ruleset/AccountEntrypoint.ts

@@ -194,7 +194,11 @@ export const AccountEntrypointProvider = () =>
         { concurrency: 10 },
       );
       return rows.filter(
-        (row): row is AccountEntrypointAttributes => row !== undefined,
+        (row): row is AccountEntrypointAttributes =>
+          // An entrypoint with zero rules is inert — it's what destroy
+          // leaves behind after emptying the rules we own. Don't surface
+          // it as a resource.
+          row !== undefined && row.rules.length > 0,
       );
     }),
 

package/src/Cloudflare/Ruleset/Ruleset.ts

@@ -156,13 +156,23 @@ export const RulesetProvider = () =>
       return toRulesetAttributes(zoneId, ruleset);
     }),
     delete: Effect.fn(function* ({ olds, output }) {
+      // This resource owns the entire phase entrypoint, so destroy removes
+      // the entrypoint ruleset itself (emptying the rules would leave an
+      // inert-but-listed entrypoint behind on the zone forever). Observe
+      // first so the delete is idempotent and never acts on a stale id.
+      const entrypoint = yield* rulesets
+        .getPhasForZone({
+          zoneId: output.zoneId,
+          rulesetPhase: output.phase ?? olds.phase,
+        })
+        .pipe(
+          Effect.catchTag("RulesetNotFound", () => Effect.succeed(undefined)),
+        );
+      if (entrypoint === undefined) return;
       yield* rulesets
-        .putPhasForZone({
+        .deleteRulesetForZone({
           zoneId: output.zoneId,
-          rulesetPhase: olds.phase,
-          name: output.name,
-          description: output.description,
-          rules: [],
+          rulesetId: entrypoint.id,
         })
         .pipe(Effect.catchTag("RulesetNotFound", () => Effect.void));
     }),
@@ -221,7 +231,11 @@ export const RulesetProvider = () =>
             ),
             Effect.map((items) =>
               items.filter(
-                (item): item is Ruleset["Attributes"] => item !== undefined,
+                (item): item is Ruleset["Attributes"] =>
+                  // An entrypoint with zero rules is inert — it's what other
+                  // owners (e.g. Worker redirect cleanup) leave behind after
+                  // removing their rules. Don't surface it as a resource.
+                  item !== undefined && item.rules.length > 0,
               ),
             ),
             // Plan-gated / partially-provisioned zones reject the route.

package/src/Cloudflare/Rum/Site.ts

@@ -327,10 +327,17 @@ const findSite = (
     Stream.runCollect,
     Effect.map((chunk) =>
       Array.from(chunk)
-        .filter(
-          (site) =>
-            (host !== undefined && site.host === host) ||
-            (zoneTag !== undefined && site.ruleset?.zoneTag === zoneTag),
+        .filter((site) =>
+          host !== undefined
+            ? site.host === host
+            : // A zone-identity site has no `host`. Host-scoped sites on the
+              // zone's subdomains ALSO carry `ruleset.zoneTag`, so a zone
+              // probe must only match true zone sites — otherwise an
+              // unrelated host site satisfies the probe and the engine
+              // refuses adoption with OwnedBySomeoneElse.
+              zoneTag !== undefined &&
+              !site.host &&
+              site.ruleset?.zoneTag === zoneTag,
         )
         .sort((a, b) => (a.created ?? "").localeCompare(b.created ?? ""))
         .at(0),

package/src/Cloudflare/StateStore/Api.ts

@@ -103,7 +103,7 @@ export default Worker(
   {
     name: STATE_STORE_SCRIPT_NAME,
     main: import.meta.url,
-    url: true,
+    workersDev: true,
     compatibility: {
       flags: ["nodejs_compat"],
       date: "2026-03-17",

package/src/Cloudflare/Tunnel/Tunnel.ts

@@ -2,6 +2,7 @@ import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Redacted from "effect/Redacted";
+import * as Schedule from "effect/Schedule";
 import * as Stream from "effect/Stream";
 
 import { isResolved } from "../../Diff.ts";
@@ -322,12 +323,33 @@ export const TunnelProvider = () =>
       };
     }),
     delete: Effect.fn(function* ({ output }) {
+      // Observe — an already-(soft-)deleted tunnel means nothing to do.
+      const observed = yield* zeroTrust
+        .getTunnelCloudflared({
+          accountId: output.accountId,
+          tunnelId: output.tunnelId,
+        })
+        .pipe(
+          Effect.catchTag("TunnelNotFound", () => Effect.succeed(undefined)),
+        );
+      if (observed === undefined || observed.deletedAt != null) return;
+      // Delete — sibling route/config deletions propagate asynchronously and
+      // Cloudflare transiently rejects the tunnel delete while they drain.
+      // Retry bounded and let a persistent failure surface: a swallowed
+      // failure silently leaks the tunnel.
       yield* zeroTrust
         .deleteTunnelCloudflared({
           accountId: output.accountId,
           tunnelId: output.tunnelId,
         })
-        .pipe(Effect.catch(() => Effect.void));
+        .pipe(
+          Effect.retry({
+            schedule: Schedule.max([
+              Schedule.spaced("3 seconds"),
+              Schedule.recurs(10),
+            ]),
+          }),
+        );
     }),
     read: Effect.fn(function* ({ id, output, olds }) {
       const { accountId } = yield* yield* CloudflareEnvironment;

package/src/Cloudflare/Website/StaticSite.ts

@@ -6,10 +6,15 @@ import * as Command from "../../Command/index.ts";
 import type { Input, InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
 import * as Output from "../../Output.ts";
-import { effectClass } from "../../Util/effect.ts";
+import {
+  effectClass,
+  isYieldableEffectLike,
+  type YieldableEffectLike,
+} from "../../Util/effect.ts";
 import { asEffect } from "../../Util/types.ts";
 import type { Providers } from "../Providers.ts";
 import type { AssetsConfig } from "../Workers/Assets.ts";
+import { isContainerDecl } from "../Workers/WorkerAsyncBindings.ts";
 import {
   Worker,
   type NormalizedBindings,
@@ -95,13 +100,21 @@ type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
  * @category Workers & Compute
  *
  * @section Basic Usage
- * Point `command` at your build script, `outdir` at where it writes
- * output, and `main` at a Worker entrypoint that serves the assets.
- * Alchemy runs the command, hashes the output, and deploys the
- * Worker bound to the built assets.
+ * 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.
  *
- * The Worker receives an `ASSETS` binding it can delegate to. A
- * minimal passthrough Worker looks like:
+ * @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
@@ -111,7 +124,7 @@ type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
  * };
  * ```
  *
- * @example Deploying a Hugo site
+ * @example Custom Worker in front of the assets
  * ```typescript
  * const site = yield* Cloudflare.Website.StaticSite("Blog", {
  *   command: "hugo --minify",
@@ -167,6 +180,25 @@ type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
  * });
  * ```
  *
+ * @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,
+ *   },
+ * });
+ * ```
+ *
  * @section 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
@@ -233,7 +265,7 @@ const makeStaticSite = <
             cwd:
               props.dev.cwd ??
               (typeof props.cwd === "string" ? props.cwd : undefined),
-            env: serializeEnv(props.dev.env ?? props.env),
+            env: yield* serializeEnv(props.dev.env ?? props.env),
           }).pipe(
             Effect.map((d) =>
               Output.map(d.url, (url) => ({
@@ -250,17 +282,12 @@ const makeStaticSite = <
           cwd: props.cwd,
           memo: props.memo,
           outdir: props.outdir,
-          env: serializeEnv(props.env),
+          env: yield* serializeEnv(props.env),
         });
 
-    // Pure-static sites don't need a custom Worker entrypoint —
-    // delegate every request straight to the ASSETS binding. Only
-    // injected when the user provided neither `main` nor `script`.
-    const fallbackScript =
-      props.main == null && props.script == null
-        ? `export default { fetch: (request, env) => env.ASSETS.fetch(request) };`
-        : undefined;
-
+    // 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.
     return yield* Worker<Bindings, WorkerAssetsConfig, Req>("Worker", {
       ...props,
       assets: build
@@ -274,21 +301,83 @@ const makeStaticSite = <
       // is serving the content. The Worker resource still exists in
       // state with a stub Attributes shape.
       dev: dev ? { mode: "external", url: dev.url } : undefined,
-      script: fallbackScript ?? props.script,
+      script: props.script,
     });
   }).pipe(Namespace.push(id));
 
-const serializeEnv = (
+/**
+ * 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
   >,
-) =>
-  Object.fromEntries(
-    Object.entries(env ?? {}).flatMap(([k, v]) => {
-      if (v === undefined) return [];
-      if (typeof v === "string" || Redacted.isRedacted(v)) return [[k, v]];
-      return [[k, JSON.stringify(v)]];
-    }),
-  );
+) {
+  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);

package/src/Cloudflare/Website/Vite.ts

@@ -47,28 +47,34 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * ```
  *
  * @section SSR Frameworks
- * For SSR frameworks like TanStack Start or SolidStart, enable
- * `nodejs_compat` so the server bundle can use Node.js APIs.
+ * SSR frameworks like TanStack Start or SolidStart work with a single
+ * call — the `nodejs_compat` compatibility flag is enabled by default
+ * so the server bundle can use Node.js APIs.
  *
  * @example TanStack Start
  * ```typescript
- * const app = yield* Cloudflare.Website.Vite("TanStackStart", {
- *   compatibility: {
- *     flags: ["nodejs_compat"],
- *   },
- * });
+ * const app = yield* Cloudflare.Website.Vite("TanStackStart");
  * ```
  *
  * @example SolidStart with worker-first routing
  * ```typescript
  * const app = yield* Cloudflare.Website.Vite("SolidStart", {
- *   compatibility: {
- *     flags: ["nodejs_compat"],
- *   },
  *   assets: { runWorkerFirst: true },
  * });
  * ```
  *
+ * @example React Router
+ * React Router's server build (`virtual:react-router/server-build`) is a
+ * build manifest with no default export, so it cannot be deployed as the
+ * Worker entry directly. Point `main` at a module that wraps it with
+ * `createRequestHandler` (React Router's Cloudflare template ships this
+ * as `workers/app.ts`):
+ * ```typescript
+ * const app = yield* Cloudflare.Website.Vite("ReactRouter", {
+ *   main: "workers/app.ts",
+ * });
+ * ```
+ *
  * @section React Server Components
  * Frameworks that emit more than one server environment (e.g. React
  * Server Components, which split into an `rsc` environment and an `ssr`
@@ -80,9 +86,6 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * @example React Router with RSC
  * ```typescript
  * const app = yield* Cloudflare.Website.Vite("ReactRouterRSC", {
- *   compatibility: {
- *     flags: ["nodejs_compat"],
- *   },
  *   viteEnvironments: {
  *     entry: "rsc",
  *     children: ["ssr"],
@@ -116,9 +119,6 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * @example Vue SPA
  * ```typescript
  * const app = yield* Cloudflare.Website.Vite("Vue", {
- *   compatibility: {
- *     flags: ["nodejs_compat"],
- *   },
  *   assets: {
  *     htmlHandling: "auto-trailing-slash",
  *     notFoundHandling: "single-page-application",
@@ -140,6 +140,22 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  * });
  * ```
  *
+ * @example Rebuilding when a sibling workspace package changes
+ * The default scope only hashes files under the project root (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.Vite("Web", {
+ *   rootDir: "apps/web",
+ *   memo: {
+ *     include: ["**\/*", "../../packages/env/src/**"],
+ *     lockfile: true,
+ *   },
+ * });
+ * ```
+ *
  * @section Class Form
  * Calling `Vite` with no arguments returns a constructor you can
  * `extend` to declare the Worker as a named class. The class is both
@@ -148,9 +164,7 @@ export interface ViteProps<Bindings extends WorkerBindingProps = {}>
  *
  * @example Declaring a Worker class
  * ```typescript
- * class Website extends Cloudflare.Website.Vite<Website>()("Website", {
- *   compatibility: { flags: ["nodejs_compat"] },
- * }) {}
+ * class Website extends Cloudflare.Website.Vite<Website>()("Website") {}
  *
  * const site = yield* Website;
  * ```