alchemy 0.47.0 → 0.48.1

package/src/alchemy.ts

@@ -20,50 +20,6 @@ import type { LoggerApi } from "./util/cli.ts";
 import { logger } from "./util/logger.ts";
 import { TelemetryClient } from "./util/telemetry/client.ts";
 
-/**
- * Parses CLI arguments to extract alchemy options
- */
-function parseCliArgs(): Partial<AlchemyOptions> {
-  const args = process.argv.slice(2);
-  const options: Partial<AlchemyOptions> = {};
-
-  // Parse phase from CLI arguments
-  if (args.includes("--destroy")) {
-    options.phase = "destroy";
-  } else if (args.includes("--read")) {
-    options.phase = "read";
-  }
-
-  if (args.includes("--local") || args.includes("--dev")) {
-    options.dev = "prefer-local";
-  } else if (
-    args.includes("--remote") ||
-    args.includes("--watch") ||
-    process.execArgv.includes("--watch")
-  ) {
-    options.dev = "prefer-remote";
-  }
-
-  // Parse quiet flag
-  if (args.includes("--quiet")) {
-    options.quiet = true;
-  }
-
-  // Parse stage argument (--stage my-stage)
-  const stageIndex = args.indexOf("--stage");
-  if (stageIndex !== -1 && stageIndex + 1 < args.length) {
-    options.stage = args[stageIndex + 1];
-  }
-  options.stage ??= process.env.STAGE;
-
-  // Get password from environment variables
-  if (process.env.ALCHEMY_PASSWORD) {
-    options.password = process.env.ALCHEMY_PASSWORD;
-  }
-
-  return options;
-}
-
 /**
  * Type alias for semantic highlighting of `alchemy` as a type keyword
  */
@@ -175,8 +131,25 @@ async function _alchemy(
   if (typeof args[0] === "string") {
     const [appName, options] = args as [string, AlchemyOptions?];
 
-    // Parse CLI arguments and merge with provided options (explicit options take precedence)
-    const cliOptions = parseCliArgs();
+    const cliArgs = process.argv.slice(2);
+    const cliOptions = {
+      phase: cliArgs.includes("--destroy")
+        ? "destroy"
+        : cliArgs.includes("--read")
+          ? "read"
+          : "up",
+      local: cliArgs.includes("--local") || cliArgs.includes("--dev"),
+      watch: cliArgs.includes("--watch"),
+      quiet: cliArgs.includes("--quiet"),
+      // Parse stage argument (--stage my-stage) functionally and inline as a property declaration
+      stage: (function parseStage() {
+        const i = cliArgs.indexOf("--stage");
+        return i !== -1 && i + 1 < cliArgs.length
+          ? cliArgs[i + 1]
+          : process.env.STAGE;
+      })(),
+      password: process.env.ALCHEMY_PASSWORD,
+    } satisfies Partial<AlchemyOptions>;
     const mergedOptions = {
       ...cliOptions,
       ...options,
@@ -348,11 +321,17 @@ export interface AlchemyOptions {
    */
   phase?: Phase;
   /**
-   * Determines how Alchemy will run in development mode.
+   * Determines if resources should be simulated locally (where possible)
+   *
+   * @default - `true` if ran with `alchemy dev` or `bun ./alchemy.run.ts --dev`
+   */
+  local?: boolean;
+  /**
+   * Determines if local changes to resources should be reactively pushed to the local or remote environment.
    *
-   * @default - `"prefer-local"` if `--dev` or `--local` is passed as a CLI argument, `"prefer-remote"` if `--remote` or `--watch` is passed as a CLI argument, `undefined` otherwise
+   * @default - `true` if ran with `alchemy dev`, `alchemy watch`, `bun --watch ./alchemy.run.ts`
    */
-  dev?: "prefer-local" | "prefer-remote";
+  watch?: boolean;
   /**
    * Name to scope the resource state under (e.g. `.alchemy/{stage}/..`).
    *

package/src/cloudflare/astro.ts

@@ -85,5 +85,8 @@ export async function Astro<B extends Bindings>(
       run_worker_first: false,
     },
     wrangler,
+    dev: props.dev ?? {
+      command: "astro dev",
+    },
   });
 }

package/src/cloudflare/compatibility-date.gen.ts

@@ -0,0 +1,7 @@
+// This file is auto-generated during build
+// Do not edit manually
+
+/**
+ * The default Cloudflare Workers compatibility date, set based on the latest workerd release at the time of build.
+ */
+export const DEFAULT_COMPATIBILITY_DATE = "2025-07-15";

package/src/cloudflare/container.ts

@@ -191,7 +191,7 @@ export async function Container<T>(
     adopt: props.adopt,
   };
 
-  const isDev = Scope.current.dev && !props.dev?.remote;
+  const isDev = Scope.current.local && !props.dev?.remote;
   if (isDev) {
     const image = await Image(id, {
       name: `cloudflare-dev/${name}`, // prefix used by Miniflare

package/src/cloudflare/d1-migrations.ts

@@ -319,9 +319,6 @@ export async function applyMigrations(
 
     if (applied.has(migrationName)) continue;
 
-    // Run the migration SQL
-    await executeD1SQL(options, migration.sql);
-
     // Generate a migration id: prefer sequential zero-padded numeric ids (e.g. 00014)
     // to keep consistency with legacy/imported data. If we cannot produce a numeric id
     // (e.g. existing IDs are not numeric), fall back to a unique timestamp-based ID.
@@ -334,26 +331,16 @@ export async function applyMigrations(
         Date.now().toString() + Math.random().toString(36).substr(2, 9);
     }
 
-    const insertSQL = `INSERT INTO ${options.migrationsTable} (id, name, applied_at) VALUES (?, ?, datetime('now'));`;
-
-    // Use parameterised query to record the migration
-    const response = await options.api.post(
-      `/accounts/${options.accountId}/d1/database/${options.databaseId}/query`,
-      {
-        sql: insertSQL,
-        params: [migrationId, migrationName],
-      },
+    // Run and record the migration in a single request.
+    // D1 over HTTP doesn't support transactions, so this is the next best thing.
+    await executeD1SQL(
+      options,
+      [
+        migration.sql,
+        `INSERT INTO ${options.migrationsTable} (id, name, applied_at) VALUES ('${migrationId}', '${migrationName}', datetime('now'));`,
+      ].join("\n"),
     );
 
-    if (!response.ok) {
-      await handleApiError(
-        response,
-        "inserting migration record",
-        "D1 database",
-        options.databaseId,
-      );
-    }
-
     if (!options.quiet) {
       logger.log(`Applied migration: ${migrationName}`);
     }

package/src/cloudflare/index.ts

@@ -12,6 +12,7 @@ export * from "./bound.ts";
 export * from "./browser-rendering.ts";
 export * from "./bucket.ts";
 export * from "./certificate-pack.ts";
+export * from "./compatibility-date.gen.ts";
 export * from "./container.ts";
 export * from "./custom-domain.ts";
 export * from "./d1-clone.ts";

package/src/cloudflare/miniflare/miniflare-worker-options.ts

@@ -17,6 +17,7 @@ export type MiniflareWorkerOptions = Pick<
   | "compatibilityDate"
   | "compatibilityFlags"
   | "format"
+  | "assets"
 > & {
   name: string;
   bundle: WorkerBundle;
@@ -209,6 +210,7 @@ function buildRemoteBinding(
 
 export async function buildMiniflareWorkerOptions({
   name: workerName,
+  assets,
   bundle,
   bindings,
   format,
@@ -232,7 +234,9 @@ export async function buildMiniflareWorkerOptions({
     ),
     compatibilityDate,
     compatibilityFlags,
-    unsafeDirectSockets: [{ entrypoint: undefined, proxy: true }],
+    // This was true for compatibility with the dev registry, but that doesn't work anyway,
+    // and if we don't set it to false, websocket connections fail. I'm confused.
+    unsafeDirectSockets: [{ proxy: false }],
     containerEngine: {
       localDocker: {
         socketPath:
@@ -291,6 +295,14 @@ export async function buildMiniflareWorkerOptions({
         options.assets = {
           binding: name,
           directory: binding.path,
+          routerConfig: {
+            invoke_user_worker_ahead_of_assets:
+              assets?.run_worker_first === true,
+          },
+          assetConfig: {
+            html_handling: assets?.html_handling,
+            not_found_handling: assets?.not_found_handling,
+          },
         };
         break;
       }

package/src/cloudflare/miniflare/miniflare-worker-proxy.ts

@@ -0,0 +1,97 @@
+import type http from "node:http";
+import { WebSocket, WebSocketServer } from "ws";
+import { HTTPServer } from "../../util/http.ts";
+
+export interface MiniflareWorkerProxyOptions {
+  /**
+   * Used to proxy websocket connections to the worker.
+   * (This is a hack; used because trying to interact with `response.webSocket` doesn't work on Bun.)
+   */
+  getDirectURL: () => Promise<URL>;
+  /** Used to proxy HTTP requests to the worker. */
+  fetch: (request: Request) => Promise<Response>;
+}
+
+export class MiniflareWorkerProxy extends HTTPServer {
+  wsServer: WebSocketServer;
+  wsReconnectAttempts = new Map<string, number>();
+
+  constructor(private readonly options: MiniflareWorkerProxyOptions) {
+    super({
+      fetch: options.fetch,
+    });
+    this.wsServer = new WebSocketServer({ noServer: true });
+    this.httpServer.on("upgrade", async (req, socket, head) => {
+      this.wsServer.handleUpgrade(req, socket, head, async (client) => {
+        const id = crypto.randomUUID();
+        await this.handleUpgrade(id, client, req);
+      });
+    });
+  }
+
+  private async handleUpgrade(
+    id: string,
+    client: WebSocket,
+    request: http.IncomingMessage,
+  ) {
+    const attempt = this.wsReconnectAttempts.get(id) ?? 0;
+    this.wsReconnectAttempts.set(id, attempt + 1);
+    if (attempt > 3) {
+      client.close(1006, "Too many reconnect attempts");
+      return;
+    }
+    if (attempt > 0) {
+      const delay = attempt * 1000;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+
+    const target = await this.options.getDirectURL();
+    const url = new URL(request.url ?? "/", target);
+    const headers = { ...request.headers };
+    // All of these headers are set by the WebSocket constructor,
+    // so if we don't delete them, the request will fail.
+    delete headers.host;
+    delete headers.connection;
+    delete headers.upgrade;
+    delete headers["sec-websocket-version"];
+    delete headers["sec-websocket-key"];
+    delete headers["sec-websocket-protocol"];
+    delete headers["sec-websocket-extensions"];
+    delete headers["sec-websocket-accept"];
+    const server = new WebSocket(url.toString(), {
+      protocol: request.headers["sec-websocket-protocol"],
+      key: request.headers["sec-websocket-key"],
+      headers,
+    });
+    server.on("open", () => {
+      // Reset the reconnect attempts when the connection is established successfully.
+      this.wsReconnectAttempts.set(id, 0);
+    });
+    server.on("message", (data, binary) => {
+      client.send(data, { binary });
+    });
+    server.on("close", async (code, reason) => {
+      if (code === 1006) {
+        // When the worker hot reloads, the websocket connection is closed with this code.
+        // Reconnecting allows the client to maintain the same connection.
+        await this.handleUpgrade(id, client, request);
+        return;
+      }
+      client.close(code, reason);
+    });
+    client.on("message", (data, binary) => {
+      server.send(data, { binary });
+    });
+    client.on("close", (code, reason) => {
+      this.wsReconnectAttempts.delete(id);
+      if (server.readyState === WebSocket.OPEN) {
+        server.close(code, reason);
+      }
+    });
+  }
+
+  async close() {
+    this.wsServer.close();
+    await super.close();
+  }
+}

package/src/cloudflare/miniflare/miniflare.ts

@@ -7,7 +7,6 @@ import {
 } from "miniflare";
 import path from "node:path";
 import { findOpenPort } from "../../util/find-open-port.ts";
-import { HTTPServer } from "../../util/http-server.ts";
 import { logger } from "../../util/logger.ts";
 import {
   promiseWithResolvers,
@@ -18,6 +17,7 @@ import {
   buildRemoteBindings,
   type MiniflareWorkerOptions,
 } from "./miniflare-worker-options.ts";
+import { MiniflareWorkerProxy } from "./miniflare-worker-proxy.ts";
 import {
   createRemoteProxyWorker,
   type RemoteBindingProxy,
@@ -26,12 +26,12 @@ import {
 class MiniflareServer {
   miniflare?: Miniflare;
   workers = new Map<string, WorkerOptions>();
-  servers = new Map<string, HTTPServer>();
+  workerProxies = new Map<string, MiniflareWorkerProxy>();
   remoteBindingProxies = new Map<string, RemoteBindingProxy>();
 
   stream = new WritableStream<{
     worker: MiniflareWorkerOptions;
-    promise: PromiseWithResolvers<HTTPServer>;
+    promise: PromiseWithResolvers<MiniflareWorkerProxy>;
   }>({
     write: async ({ worker, promise }) => {
       try {
@@ -48,7 +48,7 @@ class MiniflareServer {
   writer = this.stream.getWriter();
 
   async push(worker: MiniflareWorkerOptions) {
-    const promise = promiseWithResolvers<HTTPServer>();
+    const promise = promiseWithResolvers<MiniflareWorkerProxy>();
     const [, server] = await Promise.all([
       this.writer.write({ worker, promise }),
       promise.promise,
@@ -62,11 +62,10 @@ class MiniflareServer {
 
   private async set(worker: MiniflareWorkerOptions) {
     this.workers.set(
-      worker.name as string,
+      worker.name,
       await buildMiniflareWorkerOptions({
         ...worker,
-        remoteProxyConnectionString:
-          await this.maybeCreateMixedModeProxy(worker),
+        remoteProxyConnectionString: await this.maybeCreateRemoteProxy(worker),
       }),
     );
     if (this.miniflare) {
@@ -90,33 +89,41 @@ class MiniflareServer {
       this.miniflare = new Miniflare(await this.miniflareOptions());
       await withErrorRewrite(this.miniflare.ready);
     }
-    const existing = this.servers.get(worker.name);
+    const existing = this.workerProxies.get(worker.name);
     if (existing) {
       return existing;
     }
-    const server = new HTTPServer({
-      port: worker.port ?? (await findOpenPort()),
-      fetch: this.createRequestHandler(worker.name as string),
+    const server = new MiniflareWorkerProxy({
+      getDirectURL: async () => {
+        const url = await this.miniflare?.unsafeGetDirectURL(worker.name);
+        if (!url) {
+          throw new Error(`Worker "${worker.name}" is not running`);
+        }
+        return url;
+      },
+      fetch: this.createRequestHandler(worker.name),
     });
-    this.servers.set(worker.name, server);
-    await server.ready;
+    this.workerProxies.set(worker.name, server);
+    await server.listen(worker.port ?? (await findOpenPort()));
     return server;
   }
 
   private async dispose() {
     await Promise.all([
       this.miniflare?.dispose(),
-      ...Array.from(this.servers.values()).map((server) => server.stop()),
+      ...Array.from(this.workerProxies.values()).map((server) =>
+        server.close(),
+      ),
       ...Array.from(this.remoteBindingProxies.values()).map((proxy) =>
-        proxy.server.stop(),
+        proxy.server.close(),
       ),
     ]);
     this.miniflare = undefined;
     this.workers.clear();
-    this.servers.clear();
+    this.workerProxies.clear();
   }
 
-  private async maybeCreateMixedModeProxy(
+  private async maybeCreateRemoteProxy(
     worker: MiniflareWorkerOptions,
   ): Promise<RemoteProxyConnectionString | undefined> {
     const bindings = buildRemoteBindings(worker);
@@ -130,6 +137,8 @@ class MiniflareServer {
       )
     ) {
       return existing.connectionString;
+    } else if (existing) {
+      await existing.server.close();
     }
     const proxy = await createRemoteProxyWorker({
       name: `mixed-mode-proxy-${crypto.randomUUID()}`,
@@ -150,8 +159,8 @@ class MiniflareServer {
             },
           );
         }
-        const miniflare = await this.miniflare?.getWorker(name);
-        if (!miniflare) {
+        const worker = await this.miniflare?.getWorker(name);
+        if (!worker) {
           return new Response(
             `[Alchemy] Cannot find worker "${name}". Please try again.`,
             {
@@ -159,12 +168,12 @@ class MiniflareServer {
             },
           );
         }
-        const res = await miniflare.fetch(req.url, {
+        const res = await worker.fetch(req.url, {
           method: req.method,
           headers: req.headers as any,
           body: req.body as any,
-          redirect: "manual",
           duplex: "half",
+          redirect: "manual",
         });
         return res as unknown as Response;
       } catch (error) {

package/src/cloudflare/miniflare/remote-binding-proxy.ts

@@ -1,5 +1,5 @@
 import type { RemoteProxyConnectionString } from "miniflare";
-import { HTTPServer } from "../../util/http-server.ts";
+import { HTTPServer } from "../../util/http.ts";
 import { extractCloudflareResult } from "../api-response.ts";
 import { createCloudflareApi, type CloudflareApi } from "../api.ts";
 import type { WorkerBindingSpec } from "../bindings.ts";
@@ -22,6 +22,12 @@ interface WorkersPreviewSession {
   token: string;
 }
 
+export interface RemoteBindingProxy {
+  server: HTTPServer;
+  bindings: WorkerBindingSpec[];
+  connectionString: RemoteProxyConnectionString;
+}
+
 export async function createRemoteProxyWorker(input: {
   name: string;
   bindings: WorkerBindingSpec[];
@@ -47,62 +53,44 @@ export async function createRemoteProxyWorker(input: {
     }),
     import("../worker-subdomain.ts").then((m) => m.getAccountSubdomain(api)),
   ]);
-  return new RemoteBindingProxy(
-    `https://${input.name}.${subdomain}.workers.dev`,
-    token,
-    input.bindings,
-  );
-}
 
-export class RemoteBindingProxy {
-  server: HTTPServer;
+  const proxyURL = new URL(`https://${input.name}.${subdomain}.workers.dev`);
+  const server = new HTTPServer({
+    fetch: async (req) => {
+      const origin = new URL(req.url);
+      const url = new URL(origin.pathname, proxyURL.toString());
+      url.search = origin.search;
+      url.hash = origin.hash;
 
-  constructor(
-    readonly url: string,
-    readonly token: string,
-    readonly bindings: WorkerBindingSpec[],
-  ) {
-    this.server = new HTTPServer({
-      fetch: this.fetch.bind(this),
-    });
-  }
+      const requestHeaders = new Headers(req.headers);
+      requestHeaders.set("cf-workers-preview-token", token);
+      requestHeaders.set("host", proxyURL.hostname);
+      requestHeaders.delete("cf-connecting-ip");
 
-  get connectionString() {
-    const hostname =
-      this.server.hostname === "::" ? "localhost" : this.server.hostname;
-    return new URL(
-      `http://${hostname}:${this.server.port}`,
-    ) as RemoteProxyConnectionString;
-  }
-
-  async fetch(req: Request) {
-    const origin = new URL(req.url);
-    const url = new URL(origin.pathname, this.url);
-    url.search = origin.search;
-    url.hash = origin.hash;
-
-    const headers = new Headers(req.headers);
-    headers.set("cf-workers-preview-token", this.token);
-    headers.set("host", new URL(this.url).hostname);
-    headers.delete("cf-connecting-ip");
-
-    const res = await fetch(url, {
-      method: req.method,
-      headers,
-      body: req.body,
-      redirect: "manual",
-    });
+      const res = await fetch(url, {
+        method: req.method,
+        headers: requestHeaders,
+        body: req.body,
+        redirect: "manual",
+      });
 
-    // Remove headers that are not supported by miniflare
-    const responseHeaders = new Headers(res.headers);
-    responseHeaders.delete("transfer-encoding");
-    responseHeaders.delete("content-encoding");
+      // Remove headers that are not supported by miniflare
+      const responseHeaders = new Headers(res.headers);
+      responseHeaders.delete("transfer-encoding");
+      responseHeaders.delete("content-encoding");
 
-    return new Response(res.body, {
-      status: res.status,
-      headers: responseHeaders,
-    });
-  }
+      return new Response(res.body, {
+        status: res.status,
+        headers: responseHeaders,
+      });
+    },
+  });
+  await server.listen();
+  return {
+    server,
+    bindings: input.bindings,
+    connectionString: new URL(server.url) as RemoteProxyConnectionString,
+  };
 }
 
 async function createWorkersPreviewToken(

package/src/cloudflare/nuxt.ts

@@ -64,5 +64,8 @@ export async function Nuxt<B extends Bindings>(
     compatibilityFlags: ["nodejs_compat", ...(props?.compatibilityFlags ?? [])],
     // Enable wrangler by default, common for Nuxt/Cloudflare deployments
     wrangler: props?.wrangler ?? true,
+    dev: props?.dev ?? {
+      command: "nuxt dev",
+    },
   });
 }

package/src/cloudflare/oauth.ts

@@ -7,7 +7,7 @@ import os from "node:os";
 import path from "node:path";
 import open from "open";
 import xdgAppPaths from "xdg-app-paths";
-import { HTTPServer } from "../util/http-server.ts";
+import { HTTPServer } from "../util/http.ts";
 import { memoize } from "../util/memoize.ts";
 import {
   detached,
@@ -145,7 +145,6 @@ export const wranglerLogin = (
     return Response.redirect(`${ALCHEMY_BASE_URL}/auth/${type}`);
   };
   const server = new HTTPServer({
-    port: 8976,
     fetch: async (request) => {
       const url = new URL(request.url);
       if (url.pathname !== "/oauth/callback") {
@@ -190,6 +189,7 @@ export const wranglerLogin = (
       return renderResponse("success");
     },
   });
+  server.listen(8976);
   const timeout = setTimeout(
     () => {
       err(
@@ -204,7 +204,7 @@ export const wranglerLogin = (
   );
   return ensure(result, () => {
     clearTimeout(timeout);
-    void server.stop();
+    void server.close();
   });
 };
 

package/src/cloudflare/pipeline.ts

@@ -368,11 +368,9 @@ const PipelineResource = Resource("cloudflare::Pipeline", async function <
   let pipelineData: CloudflarePipelineResponse;
 
   if (this.phase === "create") {
-    console.log(props);
     // Check if we should adopt an existing pipeline
     try {
       // Try to create pipeline first
-      console.log("Creating new Cloudflare Pipeline:", pipelineName);
       pipelineData = await createPipeline(api, pipelineName, props);
     } catch (error) {
       // If creation fails with 409 (conflict), adopt existing pipeline
@@ -383,7 +381,7 @@ const PipelineResource = Resource("cloudflare::Pipeline", async function <
             error.message.includes("Pipeline with this name already exists")))
       ) {
         if (props.adopt) {
-          console.log(
+          console.warn(
             "Pipeline already exists, adopting existing Cloudflare Pipeline:",
             pipelineName,
           );

package/src/cloudflare/react-router.ts

@@ -41,5 +41,8 @@ export async function ReactRouter<B extends Bindings>(
             dist: props.assets.dist ?? defaultAssets,
           }
         : (props.assets ?? defaultAssets),
+    dev: props.dev ?? {
+      command: "react-router dev",
+    },
   });
 }

package/src/cloudflare/vite.ts

@@ -38,7 +38,6 @@ export async function Vite<B extends Bindings>(
         : (props.assets ?? defaultAssets),
     dev: props.dev ?? {
       command: devCommand,
-      url: "http://localhost:5173",
     },
   });
 }