alchemy 0.39.0 → 0.40.0

package/src/cloudflare/do-state-store/internal.ts

@@ -1,11 +1,9 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { bundle } from "../../esbuild/index.ts";
-import { exists } from "../../util/exists.ts";
+import { logger } from "../../util/logger.ts";
 import { withExponentialBackoff } from "../../util/retry.ts";
 import { handleApiError } from "../api-error.ts";
 import type { CloudflareApi } from "../api.ts";
 import type { WorkerMetadata } from "../worker-metadata.ts";
+import { getWorkerTemplate } from "../worker/get-worker-template.ts";
 import type { DOStateStoreAPI } from "./types.ts";
 
 interface DOStateStoreClientOptions {
@@ -84,6 +82,30 @@ export class DOStateStoreClient {
     });
   }
 
+  async waitUntilReady(): Promise<void> {
+    // This ensures the token is correct and the worker is ready to use.
+    let last: Response | undefined;
+    let delay = 1000;
+    for (let i = 0; i < 20; i++) {
+      const res = await this.validate();
+      if (res.ok) {
+        return;
+      }
+      if (!last) {
+        logger.log("Waiting for state store deployment...");
+      }
+      last = res;
+      // Exponential backoff with jitter
+      const jitter = Math.random() * 0.1 * delay;
+      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
+      delay *= 1.5; // Increase the delay for next attempt
+      delay = Math.min(delay, 10000); // Cap at 10 seconds
+    }
+    throw new Error(
+      `Failed to access state store: ${last?.status} ${last?.statusText}`,
+    );
+  }
+
   async fetch(path: string, init: RequestInit = {}): Promise<Response> {
     const url = new URL(path, this.options.url);
     url.searchParams.set("app", this.options.app);
@@ -98,7 +120,7 @@ export class DOStateStoreClient {
   }
 }
 
-const TAG = "alchemy-state-store:2025-06-03";
+const TAG = "alchemy-state-store:2025-06-23";
 
 const cache = new Map<string, string>();
 
@@ -119,12 +141,13 @@ export async function upsertStateStoreWorker(
     return;
   }
   const formData = new FormData();
-  formData.append("worker.js", await bundleWorkerScript());
+  const worker = await getWorkerTemplate("do-state-store");
+  formData.append(worker.name, worker);
   formData.append(
     "metadata",
     new Blob([
       JSON.stringify({
-        main_module: "worker.js",
+        main_module: worker.name,
         compatibility_date: "2025-06-01",
         compatibility_flags: ["nodejs_compat"],
         bindings: [
@@ -217,27 +240,3 @@ export async function getAccountSubdomain(api: CloudflareApi) {
   cache.set(key, subdomain);
   return subdomain;
 }
-
-async function bundleWorkerScript() {
-  const thisDir =
-    typeof __dirname !== "undefined"
-      ? __dirname
-      : path.dirname(fileURLToPath(import.meta.url));
-  // we can be running from .ts or .js, so resolve it defensively
-  const workerTs = path.join(thisDir, "worker.ts");
-  const workerJs = path.join(thisDir, "worker.js");
-  const result = await bundle({
-    entryPoint: (await exists(workerTs)) ? workerTs : workerJs,
-    bundle: true,
-    format: "esm",
-    target: "es2022",
-    external: ["cloudflare:*", "node:crypto"],
-    write: false,
-  });
-  if (!result.outputFiles?.[0]) {
-    throw new Error("Failed to bundle worker.ts");
-  }
-  return new File([result.outputFiles[0].text], "worker.js", {
-    type: "application/javascript+module",
-  });
-}

package/src/cloudflare/do-state-store/store.ts

@@ -4,11 +4,8 @@ import type { Scope } from "../../scope.ts";
 import type { State, StateStore } from "../../state.ts";
 import { deserializeState } from "../../state.ts";
 import { createCloudflareApi, type CloudflareApiOptions } from "../api.ts";
-import {
-  DOStateStoreClient,
-  getAccountSubdomain,
-  upsertStateStoreWorker,
-} from "./internal.ts";
+import { getAccountSubdomain } from "../worker/subdomain.ts";
+import { DOStateStoreClient, upsertStateStoreWorker } from "./internal.ts";
 
 export interface DOStateStoreOptions extends CloudflareApiOptions {
   /**
@@ -95,33 +92,19 @@ export class DOStateStore implements StateStore {
         this.options.worker?.force ?? false,
       ),
     ]);
+    if (!subdomain) {
+      throw new Error(
+        "Failed to access state store worker because the workers.dev subdomain is not available.",
+      );
+    }
     const client = new DOStateStoreClient({
       app: this.scope.appName ?? "alchemy",
       stage: this.scope.stage,
       url: `https://${workerName}.${subdomain}.workers.dev`,
       token,
     });
-    // This ensures the token is correct and the worker is ready to use.
-    let last: Response | undefined;
-    let delay = 1000;
-    for (let i = 0; i < 20; i++) {
-      const res = await client.validate();
-      if (res.ok) {
-        return client;
-      }
-      if (!last) {
-        console.log("Waiting for state store deployment...");
-      }
-      last = res;
-      // Exponential backoff with jitter
-      const jitter = Math.random() * 0.1 * delay;
-      await new Promise((resolve) => setTimeout(resolve, delay + jitter));
-      delay *= 1.5; // Increase the delay for next attempt
-      delay = Math.min(delay, 10000); // Cap at 10 seconds
-    }
-    throw new Error(
-      `Failed to access state store: ${last?.status} ${last?.statusText}`,
-    );
+    await client.waitUntilReady();
+    return client;
   }
 
   private async getClient() {

package/src/cloudflare/images.ts

@@ -56,4 +56,18 @@
  */
 export class Images {
   public readonly type = "images";
+  public readonly dev?: {
+    remote?: boolean;
+  };
+  constructor(props?: {
+    dev?: {
+      /**
+       * Whether to run the images binding remotely instead of locally
+       * @default false
+       */
+      remote?: boolean;
+    };
+  }) {
+    this.dev = props?.dev;
+  }
 }

package/src/cloudflare/kv-namespace.ts

@@ -41,6 +41,17 @@ export interface KVNamespaceProps extends CloudflareApiOptions {
    * @default true
    */
   delete?: boolean;
+
+  /**
+   * Whether to emulate the KV namespace locally when Alchemy is running in watch mode.
+   */
+  dev?: {
+    /**
+     * Whether to run the KV namespace remotely instead of locally
+     * @default false
+     */
+    remote?: boolean;
+  };
 }
 
 /**
@@ -251,6 +262,7 @@ const _KVNamespace = Resource(
       namespaceId,
       title: props.title,
       values: props.values,
+      dev: props.dev,
       createdAt: createdAt,
       modifiedAt: Date.now(),
     });

package/src/cloudflare/queue.ts

@@ -72,6 +72,17 @@ export interface QueueProps extends CloudflareApiOptions {
    * @default false
    */
   adopt?: boolean;
+
+  /**
+   * Whether to emulate the queue locally when Alchemy is running in watch mode.
+   */
+  dev?: {
+    /**
+     * Whether to run the queue remotely instead of locally
+     * @default false
+     */
+    remote?: boolean;
+  };
 }
 
 export function isQueue(eventSource: any): eventSource is Queue {
@@ -289,6 +300,7 @@ const QueueResource = Resource("cloudflare::Queue", async function <
     createdOn: queueData.result.created_on || new Date().toISOString(),
     modifiedOn: queueData.result.modified_on || new Date().toISOString(),
     accountId: api.accountId,
+    dev: props.dev,
     // phantom properties
     Body: undefined as T,
     Batch: undefined! as MessageBatch<T>,

package/src/cloudflare/vite.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { detectPackageManager } from "../util/detect-package-manager.ts";
 import type { Assets } from "./assets.ts";
 import type { Bindings } from "./bindings.ts";
 import { Website, type WebsiteProps } from "./website.ts";
@@ -17,6 +18,13 @@ export async function Vite<B extends Bindings>(
   props: ViteProps<B>,
 ): Promise<Vite<B>> {
   const defaultAssets = path.join("dist", "client");
+  const packageManager = detectPackageManager();
+  const devCommand = {
+    npm: "npx vite dev",
+    bun: "bun vite dev",
+    pnpm: "pnpm vite dev",
+    yarn: "yarn vite dev",
+  }[packageManager];
   return Website(id, {
     ...props,
     spa: true,
@@ -27,5 +35,9 @@ export async function Vite<B extends Bindings>(
             dist: props.assets.dist ?? defaultAssets,
           }
         : (props.assets ?? defaultAssets),
+    dev: props.dev ?? {
+      command: devCommand,
+      url: "http://localhost:5173",
+    },
   });
 }

package/src/cloudflare/website.ts

@@ -94,6 +94,14 @@ export interface WebsiteProps<B extends Bindings>
    * @default false
    */
   spa?: boolean;
+
+  /**
+   * Configure the command to use in development mode
+   */
+  dev?: {
+    command: string;
+    url: string;
+  };
 }
 
 export type Website<B extends Bindings> = B extends { ASSETS: any }
@@ -114,7 +122,7 @@ export async function Website<B extends Bindings>(
     {
       parent: Scope.current,
     },
-    async () => {
+    async (scope) => {
       // directory from which all relative paths are resolved
       const cwd = path.resolve(props.cwd || process.cwd());
 
@@ -177,6 +185,13 @@ export default {
 };`,
         url: true,
         adopt: true,
+        dev: props.dev
+          ? {
+              command: props.dev.command,
+              url: props.dev.url,
+              cwd,
+            }
+          : undefined,
       } as WorkerProps<any> & { name: string };
 
       if (wrangler) {
@@ -196,7 +211,9 @@ export default {
         });
       }
 
-      if (props.command) {
+      const isDev = scope.dev && !!props.dev;
+
+      if (props.command && !isDev) {
         await Exec("build", {
           cwd,
           command: props.command,
@@ -211,10 +228,12 @@ export default {
           ...workerProps.bindings,
           // we don't include the Assets binding until after build to make sure the asset manifest is correct
           // we generate the wrangler.json using all the bind
-          ASSETS: await Assets("assets", {
-            // Assets are discovered from proces.cwd(), not Website.cwd or wrangler.jsonc
-            path: path.relative(process.cwd(), assetsDirPath),
-          }),
+          ASSETS: isDev
+            ? undefined
+            : await Assets("assets", {
+                // Assets are discovered from proces.cwd(), not Website.cwd or wrangler.jsonc
+                path: path.relative(process.cwd(), assetsDirPath),
+              }),
         },
       } as WorkerProps<any> & { name: string })) as Website<B>;
     },

package/src/cloudflare/worker/get-worker-template.ts

@@ -0,0 +1,14 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export async function getWorkerTemplate(
+  name: "do-state-store" | "mixed-mode-proxy-worker",
+) {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const path = join(dir, "..", "..", "..", "workers", `${name}.js`);
+  const template = await readFile(path, "utf8");
+  return new File([template], `${name}.js`, {
+    type: "application/javascript+module",
+  });
+}

package/src/cloudflare/worker/http-server.ts

@@ -0,0 +1,80 @@
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { Readable } from "node:stream";
+
+export class HTTPServer {
+  server: http.Server;
+  ready: Promise<void>;
+
+  constructor(options: {
+    port?: number;
+    fetch: (request: Request) => Promise<Response>;
+  }) {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    this.ready = promise;
+    this.server = http
+      .createServer(async (req, res) => {
+        const response = await options.fetch(toWebRequest(req));
+        await writeNodeResponse(res, response);
+      })
+      .listen(options.port, resolve);
+  }
+
+  get port() {
+    return (this.server.address() as AddressInfo).port;
+  }
+
+  get hostname() {
+    const address = (this.server.address() as AddressInfo)?.address;
+    if (address === "::") {
+      return "localhost";
+    }
+    return address;
+  }
+
+  get url() {
+    return `http://${this.hostname}:${this.port}`;
+  }
+
+  stop() {
+    return new Promise((resolve, reject) => {
+      this.server.close((err) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(undefined);
+        }
+      });
+    });
+  }
+}
+
+function toWebRequest(request: http.IncomingMessage): Request {
+  const method = request.method ?? "GET";
+  return new Request(`http://${request.headers.host}${request.url ?? "/"}`, {
+    method,
+    headers: request.headers as Record<string, string>,
+    body:
+      ["GET", "HEAD", "OPTIONS"].includes(method) || !request.readable
+        ? undefined
+        : (Readable.toWeb(request) as unknown as BodyInit),
+  });
+}
+
+async function writeNodeResponse(res: http.ServerResponse, response: Response) {
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
+  });
+  await response.body?.pipeTo(
+    new WritableStream({
+      write(chunk) {
+        res.write(chunk);
+      },
+      close() {
+        res.end();
+      },
+    }),
+  );
+  res.end();
+}