alchemy 0.44.4 → 0.45.1

package/src/alchemy.ts

@@ -34,12 +34,14 @@ function parseCliArgs(): Partial<AlchemyOptions> {
     options.phase = "read";
   }
 
-  if (
-    args.includes("--dev") ||
+  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 = true;
+    options.dev = "prefer-remote";
   }
 
   // Parse quiet flag
@@ -346,11 +348,11 @@ export interface AlchemyOptions {
    */
   phase?: Phase;
   /**
-   * Determines whether Alchemy will run in dev mode.
+   * Determines how Alchemy will run in development mode.
    *
-   * @default - `true` if `--dev` or `--watch` is passed as a CLI argument, `false` otherwise
+   * @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
    */
-  dev?: boolean;
+  dev?: "prefer-local" | "prefer-remote";
   /**
    * Name to scope the resource state under (e.g. `.alchemy/{stage}/..`).
    *

package/src/build-date.ts

@@ -5,4 +5,4 @@
  * The build date used as the default worker compatibility date.
  * This is set to the date when the package was built.
  */
-export const BUILD_DATE = "2025-07-08";
+export const BUILD_DATE = "2025-07-09";

package/src/cloudflare/auth.ts

@@ -100,7 +100,7 @@ async function refreshAuthToken(
 
   if (!response.ok) {
     throw new Error(
-      `Failed to refresh auth token: ${response.status} ${response.statusText}`,
+      `Failed to refresh auth token: ${response.status} ${response.statusText} ${await response.text()}`,
     );
   }
 

package/src/cloudflare/bundle/esbuild.ts

@@ -0,0 +1,194 @@
+import esbuild from "esbuild";
+import fs from "node:fs/promises";
+import path from "pathe";
+import { esbuildPluginCompatWarning } from "./plugin-compat-warning.ts";
+import { esbuildPluginHotReload } from "./plugin-hot-reload.ts";
+import { esbuildPluginHybridNodeCompat } from "./plugin-hybrid-node-compat.ts";
+import { esbuildPluginWasm } from "./plugin-wasm.ts";
+import type {
+  WorkerBundle,
+  WorkerBundleBaseProps,
+  WorkerBundleChunk,
+  WorkerBundleProvider,
+} from "./shared.ts";
+import { parseFiles } from "./shared.ts";
+
+interface ESBuildBundleProps
+  extends WorkerBundleBaseProps,
+    Omit<
+      esbuild.BuildOptions,
+      "entryPoints" | "format" | "absWorkingDir" | "outdir"
+    > {
+  entrypoint: string;
+  cwd: string;
+  outdir: string;
+}
+
+export class ESBuildBundleProvider implements WorkerBundleProvider {
+  constructor(private props: ESBuildBundleProps) {
+    // Normalize paths to ensure consistency between esbuild inputs and outputs:
+    // - the `cwd` is absolute
+    // - the `entrypoint` and `outdir` are relative to the `cwd`
+    // This is so we can identify the entrypoint from the metafile.
+    this.props.cwd = path.resolve(this.props.cwd);
+    this.props.entrypoint = path.isAbsolute(props.entrypoint)
+      ? path.relative(this.props.cwd, props.entrypoint)
+      : path.normalize(props.entrypoint);
+    this.props.outdir = path.isAbsolute(props.outdir)
+      ? path.relative(this.props.cwd, props.outdir)
+      : path.normalize(props.outdir);
+  }
+
+  async create(): Promise<WorkerBundle> {
+    const options = buildOptions(this.props);
+    const result = await esbuild.build(options);
+    return resolveOutputs(result.metafile, this.props);
+  }
+
+  async watch(signal: AbortSignal): Promise<ReadableStream<WorkerBundleChunk>> {
+    const options = buildOptions(this.props);
+
+    return new ReadableStream<WorkerBundleChunk>({
+      start: async (controller) => {
+        const context = await esbuild.context({
+          ...options,
+          plugins: [
+            ...(options.plugins ?? []),
+            esbuildPluginHotReload({
+              onBuildStart: () => {
+                controller.enqueue({ type: "start" });
+              },
+              onBuildError: (errors) => {
+                controller.enqueue({ type: "error", errors });
+              },
+              onBuildEnd: async (result) => {
+                controller.enqueue({
+                  type: "end",
+                  result: await resolveOutputs(result.metafile!, this.props),
+                });
+              },
+            }),
+          ],
+        });
+        await context.watch();
+        signal.addEventListener("abort", async () => {
+          await context.dispose();
+          controller.close();
+        });
+      },
+    });
+  }
+
+  async delete(): Promise<void> {
+    await fs.rm(path.join(this.props.cwd, this.props.outdir), {
+      recursive: true,
+      force: true,
+    });
+  }
+}
+function buildOptions({
+  entrypoint,
+  nodeCompat,
+  cwd,
+  ...props
+}: ESBuildBundleProps) {
+  return {
+    ...props,
+    entryPoints: [entrypoint],
+    absWorkingDir: cwd,
+    format: props.format,
+    target: "esnext",
+    platform: "node",
+    metafile: true,
+    write: true,
+    bundle: true,
+    conditions: ["workerd", "worker", "import", "module", "browser"],
+    mainFields: ["module", "main"],
+    loader: {
+      ".sql": "text",
+      ".json": "json",
+      ...props.loader,
+    },
+    plugins: [
+      esbuildPluginWasm(),
+      nodeCompat === "v2"
+        ? esbuildPluginHybridNodeCompat()
+        : esbuildPluginCompatWarning(nodeCompat ?? null),
+      ...(props.plugins ?? []),
+    ],
+    alias: props.alias,
+    external: [
+      ...(nodeCompat === "als" ? external_als : external),
+      ...(props.external ?? []),
+    ],
+  } satisfies esbuild.BuildOptions;
+}
+
+async function resolveOutputs(
+  metafile: esbuild.Metafile,
+  props: ESBuildBundleProps,
+): Promise<WorkerBundle> {
+  const outdir = path.resolve(props.cwd, props.outdir);
+  const paths: string[] = [];
+  let entrypoint: string | undefined;
+  for (const [key, value] of Object.entries(metafile.outputs)) {
+    const name = path.relative(outdir, path.resolve(props.cwd, key));
+    paths.push(name);
+    if (value.entryPoint === props.entrypoint) {
+      entrypoint = name;
+    }
+  }
+  if (!entrypoint) {
+    throw new Error(
+      `Failed to find entrypoint in metafile - expected ${props.entrypoint} but found ${Object.values(
+        metafile.outputs,
+      )
+        .map((v) => v.entryPoint)
+        .filter((v) => v !== undefined)
+        .join(", ")}`,
+    );
+  }
+  const { files, hash } = await parseFiles(outdir, paths, props.format);
+  return {
+    entrypoint,
+    files,
+    hash,
+  };
+}
+
+// https://developers.cloudflare.com/workers/runtime-apis/nodejs/#supported-nodejs-apis
+const nodejs_compat = [
+  "node:async_hooks",
+  "node:assert",
+  "node:buffer",
+  "node:console",
+  "node:crypto",
+  "node:debug",
+  "node:diagnostics_channel",
+  "node:dns",
+  "node:events",
+  "node:inspector",
+  "node:net",
+  "node:path",
+  "node:perf_hooks", // partially supported
+  "node:process",
+  "node:querystring",
+  "node:stream",
+  "node:string_decoder",
+  "node:timers",
+  "node:tls", // partially supported
+  "node:url",
+  "node:util",
+  "node:zlib",
+  // "node:*",
+];
+
+const external = [
+  ...nodejs_compat,
+  ...nodejs_compat.map((p) => p.split(":")[1]),
+  "cloudflare:workers",
+  "cloudflare:workflows",
+  "cloudflare:*",
+];
+
+const external_als = ["node:async_hooks", "async_hooks", "cloudflare:*"];

package/src/cloudflare/bundle/fs.ts

@@ -0,0 +1,98 @@
+import kleur from "kleur";
+import fs from "node:fs/promises";
+import path from "pathe";
+import { logger } from "../../util/logger.ts";
+import type {
+  WorkerBundle,
+  WorkerBundleBaseProps,
+  WorkerBundleChunk,
+  WorkerBundleProvider,
+} from "./shared.ts";
+import { parseFiles } from "./shared.ts";
+
+interface FSBundleProps extends WorkerBundleBaseProps {
+  entrypoint: string;
+  globs: string[] | undefined;
+  cwd: string;
+  sourcemaps: boolean;
+}
+
+export class FSBundleProvider implements WorkerBundleProvider {
+  private root: string;
+  private entrypoint: string;
+  private globs: string[];
+  private format: "esm" | "cjs";
+
+  constructor(props: FSBundleProps) {
+    const entrypoint = path.resolve(props.cwd, props.entrypoint);
+    this.root = path.dirname(entrypoint);
+    this.entrypoint = path.relative(this.root, entrypoint);
+    this.globs = props.globs ?? [
+      "**/*.js",
+      "**/*.mjs",
+      "**/*.wasm",
+      ...(props.sourcemaps ? ["**/*.js.map"] : []),
+    ];
+    this.format = props.format;
+  }
+
+  async create(log = true): Promise<WorkerBundle> {
+    const fileNames = new Set<string>();
+    await Promise.all(
+      this.globs.map(async (glob) => {
+        for await (const file of fs.glob(glob, { cwd: this.root })) {
+          fileNames.add(file);
+        }
+      }),
+    );
+    const { files, hash } = await parseFiles(
+      this.root,
+      Array.from(fileNames),
+      this.format,
+    );
+    if (log) {
+      logger.log(`${kleur.gray("worker:")} ${kleur.blue(this.entrypoint)}`);
+      logger.log(`${kleur.gray("main:")} ${kleur.blue(this.entrypoint)}`);
+      logger.log(
+        `${kleur.gray("dist:")} ${kleur.blue(path.relative(process.cwd(), this.root))}:`,
+      );
+    }
+    return {
+      entrypoint: this.entrypoint,
+      files,
+      hash,
+    };
+  }
+
+  async watch(signal: AbortSignal): Promise<ReadableStream<WorkerBundleChunk>> {
+    let result = await this.create();
+    const watcher = fs.watch(this.root, {
+      recursive: true,
+      signal,
+    });
+    const iterator = watcher[Symbol.asyncIterator]();
+    return new ReadableStream({
+      start: async (controller) => {
+        controller.enqueue({ type: "end", result });
+      },
+      pull: async (controller) => {
+        const next = await iterator.next().catch((err) => {
+          if (err instanceof DOMException && err.name === "AbortError") {
+            return { done: true };
+          }
+          throw err;
+        });
+        if (next.done) {
+          controller.close();
+        } else {
+          controller.enqueue({ type: "start" });
+          const update = await this.create(false);
+          if (update.hash !== result.hash) {
+            result = update;
+            controller.enqueue({ type: "end", result });
+          }
+        }
+      },
+    });
+  }
+}

package/src/cloudflare/bundle/index.ts

@@ -0,0 +1,6 @@
+export { normalizeWorkerBundle } from "./normalize.ts";
+export type {
+  WorkerBundle,
+  WorkerBundleChunk,
+  WorkerBundleProvider,
+} from "./shared.ts";

package/src/cloudflare/bundle/inline.ts

@@ -0,0 +1,42 @@
+import crypto from "node:crypto";
+import type {
+  WorkerBundle,
+  WorkerBundleBaseProps,
+  WorkerBundleChunk,
+  WorkerBundleProvider,
+} from "./shared.ts";
+
+interface InlineBundleProps extends WorkerBundleBaseProps {
+  content: string;
+}
+
+export class InlineBundleProvider implements WorkerBundleProvider {
+  constructor(private props: InlineBundleProps) {}
+
+  async create(): Promise<WorkerBundle> {
+    return {
+      entrypoint: "worker.js",
+      files: [
+        new File([this.props.content], "worker.js", {
+          type:
+            this.props.format === "cjs"
+              ? "application/javascript"
+              : "application/javascript+module",
+        }),
+      ],
+      hash: crypto
+        .createHash("sha256")
+        .update(this.props.content)
+        .digest("hex"),
+    };
+  }
+
+  async watch(): Promise<ReadableStream<WorkerBundleChunk>> {
+    return new ReadableStream<WorkerBundleChunk>({
+      start: async (controller) => {
+        controller.enqueue({ type: "end", result: await this.create() });
+        controller.close();
+      },
+    });
+  }
+}

package/src/cloudflare/bundle/normalize.ts

@@ -0,0 +1,76 @@
+import type esbuild from "esbuild";
+import { ESBuildBundleProvider } from "./esbuild.ts";
+import { FSBundleProvider } from "./fs.ts";
+import { InlineBundleProvider } from "./inline.ts";
+import type { WorkerBundleProvider } from "./shared.ts";
+import { validateNodeCompat } from "./validate-node-compat.ts";
+
+interface NormalizeWorkerBundleProps {
+  script: string | undefined;
+  entrypoint: string | undefined;
+  noBundle: boolean | undefined;
+  format: "cjs" | "esm" | undefined;
+  compatibilityDate: string;
+  compatibilityFlags: string[];
+  rules:
+    | {
+        globs: string[];
+      }[]
+    | undefined;
+  bundle?: Omit<
+    esbuild.BuildOptions,
+    "entryPoints" | "format" | "absWorkingDir"
+  >;
+  cwd: string;
+  outdir: string;
+  sourceMap: boolean | undefined;
+}
+
+export function wrap<T>(fn: () => T): [T, null] | [null, Error] {
+  try {
+    return [fn(), null];
+  } catch (e) {
+    return [null, e instanceof Error ? e : new Error(String(e))];
+  }
+}
+
+export function normalizeWorkerBundle(
+  props: NormalizeWorkerBundleProps,
+): WorkerBundleProvider {
+  const nodeCompat = validateNodeCompat({
+    compatibilityDate: props.compatibilityDate,
+    compatibilityFlags: props.compatibilityFlags,
+    noBundle: props.noBundle ?? false,
+  });
+  if (props.script) {
+    return new InlineBundleProvider({
+      content: props.script,
+      format: props.format ?? "esm",
+      nodeCompat,
+    });
+  }
+  if (!props.entrypoint) {
+    throw new Error(
+      "Either `script` or `entrypoint` must be provided for workers",
+    );
+  }
+  if (props.noBundle) {
+    return new FSBundleProvider({
+      entrypoint: props.entrypoint,
+      format: props.format ?? "esm",
+      nodeCompat,
+      cwd: props.cwd,
+      globs: props.rules?.flatMap((rule) => rule.globs),
+      sourcemaps: props.sourceMap !== false,
+    });
+  }
+  return new ESBuildBundleProvider({
+    entrypoint: props.entrypoint,
+    format: props.format ?? "esm",
+    nodeCompat,
+    cwd: props.cwd,
+    outdir: props.outdir,
+    sourcemap: props.sourceMap !== false ? "linked" : undefined,
+    ...props.bundle,
+  });
+}

package/src/cloudflare/bundle/{nodejs-import-warning-plugin.ts → plugin-compat-warning.ts}

@@ -15,7 +15,7 @@ const NODE_REGEX = new RegExp(
  * - Any node:* import is found without nodejs_compat flag
  * - node:async_hooks is imported without nodejs_compat or nodejs_als flags
  */
-export function nodeJsImportWarningPlugin(mode: "als" | null): Plugin {
+export function esbuildPluginCompatWarning(mode: "als" | null): Plugin {
   return {
     name: "nodejs-import-warning",
     setup(build: PluginBuild) {
@@ -67,7 +67,9 @@ export function nodeJsImportWarningPlugin(mode: "als" | null): Plugin {
               ),
             ].join("\n"),
           );
-        } else if (alsImporters.size > 0 && !mode) {
+        }
+
+        if (alsImporters.size > 0 && !mode) {
           logger.warn(
             [
               `Detected import of ${kleur.yellow("node:async_hooks")} but ${kleur.red("nodejs_als")} compatibility flag is not set. `,

package/src/cloudflare/bundle/plugin-hot-reload.ts

@@ -0,0 +1,27 @@
+import type esbuild from "esbuild";
+
+export interface HotReloadPluginProps {
+  onBuildStart?: () => void | Promise<void>;
+  onBuildEnd?: (result: esbuild.BuildResult) => void | Promise<void>;
+  onBuildError?: (errors: esbuild.Message[]) => void | Promise<void>;
+}
+
+export function esbuildPluginHotReload(
+  props: HotReloadPluginProps,
+): esbuild.Plugin {
+  return {
+    name: "alchemy-hot-reload",
+    setup(build) {
+      if (props.onBuildStart) {
+        build.onStart(props.onBuildStart);
+      }
+      build.onEnd(async (result) => {
+        if (result.errors.length > 0) {
+          await props.onBuildError?.(result.errors);
+        } else {
+          await props.onBuildEnd?.(result);
+        }
+      });
+    },
+  };
+}

package/src/cloudflare/bundle/{nodejs-compat.ts → plugin-hybrid-node-compat.ts}

@@ -19,18 +19,18 @@ const REQUIRED_UNENV_ALIAS_NAMESPACE = "required-unenv-alias";
  *
  * @returns ESBuild plugin
  */
-export async function nodeJsCompatPlugin(): Promise<Plugin> {
-  // `unenv` and `@cloudflare/unenv-preset` only publish esm
-  const { defineEnv } = await import("unenv");
-  const { cloudflare } = await import("@cloudflare/unenv-preset");
-  const { alias, inject, external, polyfill } = defineEnv({
-    presets: [cloudflare],
-    npmShims: true,
-  }).env;
-
+export function esbuildPluginHybridNodeCompat(): Plugin {
   return {
     name: "hybrid-nodejs_compat",
-    setup(build) {
+    setup: async (build) => {
+      // `unenv` and `@cloudflare/unenv-preset` only publish esm
+      const { defineEnv } = await import("unenv");
+      const { cloudflare } = await import("@cloudflare/unenv-preset");
+      const { alias, inject, external, polyfill } = defineEnv({
+        presets: [cloudflare],
+        npmShims: true,
+      }).env;
+
       errorOnServiceWorkerFormat(build);
       handleRequireCallsToNodeJSBuiltins(build);
       handleUnenvAliasedPackages(build, alias, external);

package/src/cloudflare/bundle/plugin-wasm.ts

@@ -0,0 +1,62 @@
+import type { Plugin } from "esbuild";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export function esbuildPluginWasm(): Plugin {
+  return {
+    name: "wasm",
+    setup: (build) => {
+      // Resolve ".wasm" files to a path with a namespace
+      build.onResolve({ filter: /\.wasm$/ }, (args) => {
+        // If this is the import inside the stub module, import the
+        // binary itself. Put the path in the "wasm-binary" namespace
+        // to tell our binary load callback to load the binary file.
+        if (args.namespace === "wasm-stub") {
+          return {
+            path: args.path,
+            namespace: "wasm-binary",
+          };
+        }
+
+        // Otherwise, generate the JavaScript stub module for this
+        // ".wasm" file. Put it in the "wasm-stub" namespace to tell
+        // our stub load callback to fill it with JavaScript.
+        //
+        // Resolve relative paths to absolute paths here since this
+        // resolve callback is given "resolveDir", the directory to
+        // resolve imports against.
+        if (args.resolveDir === "") {
+          return; // Ignore unresolvable paths
+        }
+        return {
+          path: path.isAbsolute(args.path)
+            ? args.path
+            : path.join(args.resolveDir, args.path),
+          namespace: "wasm-stub",
+        };
+      });
+
+      // Virtual modules in the "wasm-stub" namespace are filled with
+      // the JavaScript code for compiling the WebAssembly binary. The
+      // binary itself is imported from a second virtual module.
+      build.onLoad({ filter: /.*/, namespace: "wasm-stub" }, async (args) => ({
+        contents: `import wasm from ${JSON.stringify(args.path)}
+            export default (imports) =>
+              WebAssembly.instantiate(wasm, imports).then(
+                result => result.instance.exports)`,
+      }));
+
+      // Virtual modules in the "wasm-binary" namespace contain the
+      // actual bytes of the WebAssembly file. This uses esbuild's
+      // built-in "binary" loader instead of manually embedding the
+      // binary data inside JavaScript code ourselves.
+      build.onLoad(
+        { filter: /.*/, namespace: "wasm-binary" },
+        async (args) => ({
+          contents: await fs.readFile(args.path),
+          loader: "binary",
+        }),
+      );
+    },
+  };
+}

package/src/cloudflare/bundle/shared.ts

@@ -0,0 +1,73 @@
+import type esbuild from "esbuild";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getContentType } from "../../util/content-type.ts";
+
+export interface WorkerBundleBaseProps {
+  format: "cjs" | "esm";
+  nodeCompat: "als" | "v2" | null;
+}
+
+export interface WorkerBundle {
+  entrypoint: string;
+  files: File[];
+  hash: string;
+}
+
+export type WorkerBundleChunk =
+  | {
+      type: "start";
+    }
+  | {
+      type: "end";
+      result: WorkerBundle;
+    }
+  | {
+      type: "error";
+      errors: esbuild.Message[];
+    };
+
+export interface WorkerBundleProvider {
+  create(): Promise<WorkerBundle>;
+  watch(signal: AbortSignal): Promise<ReadableStream<WorkerBundleChunk>>;
+  delete?(): Promise<void>;
+}
+
+export const normalizeFileType = (file: string, format: "cjs" | "esm") => {
+  if (path.extname(file) === ".js" && format === "esm") {
+    return "application/javascript+module";
+  }
+  return getContentType(file);
+};
+
+export const parseFiles = async (
+  root: string,
+  paths: string[],
+  format: "esm" | "cjs",
+) => {
+  const outputs = await Promise.all(
+    paths.map(async (file) => {
+      const content = await fs.readFile(path.join(root, file));
+      return {
+        file: new File([content], file, {
+          type: normalizeFileType(file, format),
+        }),
+        hash: crypto.createHash("sha256").update(content).digest("hex"),
+      };
+    }),
+  );
+  return {
+    files: outputs.map(({ file }) => file),
+    hash: combineFileHashes(outputs),
+  };
+};
+
+const combineFileHashes = (files: { file: File; hash: string }[]) => {
+  const sorted = files.sort((a, b) => a.file.name.localeCompare(b.file.name));
+  const finalHash = crypto.createHash("sha256");
+  for (const { hash } of sorted) {
+    finalHash.update(hash);
+  }
+  return finalHash.digest("hex");
+};