alchemy 0.63.0 → 0.64.0

package/src/cloudflare/bundle/plugin-als-external.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "esbuild";
+
+/**
+ * An esbuild plugin that will mark `node:async_hooks` imports as external.
+ */
+export const esbuildPluginAsyncLocalStorage: Plugin = {
+  name: "async-local-storage-imports",
+  setup(pluginBuild) {
+    pluginBuild.onResolve({ filter: /^node:async_hooks(\/|$)/ }, () => {
+      return { external: true };
+    });
+  },
+};

package/src/cloudflare/bundle/plugin-hybrid-node-compat.ts

@@ -4,9 +4,10 @@
 
 import type { Plugin, PluginBuild } from "esbuild";
 import assert from "node:assert";
-import module, { createRequire } from "node:module";
+import { createRequire } from "node:module";
 import nodePath from "node:path";
 import { dedent } from "../../util/dedent.ts";
+import { NODEJS_MODULES_RE } from "./nodejs-builtin-modules.ts";
 
 const _require =
   typeof require === "undefined" ? createRequire(import.meta.url) : require;
@@ -19,15 +20,34 @@ const REQUIRED_UNENV_ALIAS_NAMESPACE = "required-unenv-alias";
  *
  * @returns ESBuild plugin
  */
-export function esbuildPluginHybridNodeCompat(): Plugin {
+export function esbuildPluginHybridNodeCompat({
+  compatibilityDate,
+  compatibilityFlags,
+}: {
+  compatibilityDate?: string;
+  compatibilityFlags?: string[];
+}): Plugin {
   return {
     name: "hybrid-nodejs_compat",
-    setup: async (build) => {
+    async setup(build) {
       // `unenv` and `@cloudflare/unenv-preset` only publish esm
       const { defineEnv } = await import("unenv");
-      const { cloudflare } = await import("@cloudflare/unenv-preset");
+      const { getCloudflarePreset } = await import("@cloudflare/unenv-preset");
+
       const { alias, inject, external, polyfill } = defineEnv({
-        presets: [cloudflare],
+        presets: [
+          getCloudflarePreset({
+            compatibilityDate,
+            compatibilityFlags,
+          }),
+          {
+            alias: {
+              // Force esbuild to use the node implementation of debug instead of unenv's no-op stub.
+              // The alias is processed by handleUnenvAliasedPackages which uses require.resolve().
+              debug: "debug",
+            },
+          },
+        ],
         npmShims: true,
       }).env;
 
@@ -39,19 +59,6 @@ export function esbuildPluginHybridNodeCompat(): Plugin {
   };
 }
 
-const NODEJS_MODULES_RE = new RegExp(
-  `^(node:)?(${module.builtinModules
-    .filter(
-      (m) =>
-        ![
-          // in some runtimes (like bun), `ws` is a built-in module but is not in `node`
-          // bundling for `nodejs_compat` should not polyfill these modules
-          "ws",
-        ].includes(m),
-    )
-    .join("|")})$`,
-);
-
 /**
  * If we are bundling a "Service Worker" formatted Worker, imports of external modules,
  * which won't be inlined/bundled by esbuild, are invalid.
@@ -108,8 +115,8 @@ function handleRequireCallsToNodeJSBuiltins(build: PluginBuild) {
     ({ path }) => {
       return {
         contents: dedent`
-            import libDefault from '${path}';
-            module.exports = libDefault;`,
+          import libDefault from '${path}';
+          module.exports = libDefault;`,
         loader: "js",
       };
     },
@@ -133,7 +140,7 @@ function handleUnenvAliasedPackages(
   for (const [module, unresolvedAlias] of Object.entries(alias)) {
     try {
       aliasAbsolute[module] = _require.resolve(unresolvedAlias);
-    } catch (_e) {
+    } catch {
       // this is an alias for package that is not installed in the current app => ignore
     }
   }
@@ -144,17 +151,12 @@ function handleUnenvAliasedPackages(
 
   build.onResolve({ filter: UNENV_ALIAS_RE }, (args) => {
     const unresolvedAlias = alias[args.path];
-
     // Convert `require()` calls for NPM packages to a virtual ES Module that can be imported avoiding the require calls.
     // Note: Does not apply to Node.js packages that are handled in `handleRequireCallsToNodeJSBuiltins`
     if (
       args.kind === "require-call" &&
       (unresolvedAlias.startsWith("unenv/npm/") ||
-        unresolvedAlias.startsWith("unenv/mock/") ||
-        // this does not exist in the original wrangler code but does seem to resolve the problem
-        // TODO(sam): is this the right solution? Why does the same code work in wrangler?
-        unresolvedAlias.startsWith("@cloudflare/unenv-preset/npm/") ||
-        unresolvedAlias.startsWith("@cloudflare/unenv-preset/mock/"))
+        unresolvedAlias.startsWith("unenv/mock/"))
     ) {
       return {
         path: args.path,
@@ -200,7 +202,6 @@ function handleNodeJSGlobals(
 ) {
   const UNENV_VIRTUAL_MODULE_RE = /_virtual_unenv_global_polyfill-(.+)$/;
   const prefix = nodePath.resolve(
-    // getBasePath(),
     import.meta.dirname,
     "_virtual_unenv_global_polyfill-",
   );

package/src/cloudflare/bundle/plugin-node-compat.ts

@@ -0,0 +1,114 @@
+import type { Plugin } from "esbuild";
+import type { NodeJSCompatMode } from "miniflare";
+import { relative } from "node:path";
+import chalk from "picocolors";
+import { dedent } from "../../util/dedent.ts";
+import { logger } from "../../util/logger.ts";
+import { NODEJS_MODULES_RE } from "./nodejs-builtin-modules.ts";
+
+/**
+ * An esbuild plugin that will:
+ * - mark any `node:...` imports as external
+ * - warn if there are node imports (if not in v1 mode)
+ *
+ * Applies to: null, als, legacy and v1 modes.
+ */
+export const esbuildPluginNodeCompatImports = (
+  mode: NodeJSCompatMode,
+): Plugin => ({
+  name: "nodejs_compat-imports",
+  setup(pluginBuild) {
+    // Infinite loop detection
+    const seen = new Set<string>();
+
+    // Prevent multiple warnings per package
+    const warnedPackages = new Map<string, string[]>();
+
+    pluginBuild.onStart(() => {
+      seen.clear();
+      warnedPackages.clear();
+    });
+    pluginBuild.onResolve(
+      { filter: NODEJS_MODULES_RE },
+      async ({ path, kind, resolveDir, importer }) => {
+        const specifier = `${path}:${kind}:${resolveDir}:${importer}`;
+        if (seen.has(specifier)) {
+          return;
+        }
+
+        seen.add(specifier);
+        // Try to resolve this import as a normal package
+        const result = await pluginBuild.resolve(path, {
+          kind,
+          resolveDir,
+          importer,
+        });
+
+        if (result.errors.length > 0) {
+          // esbuild couldn't resolve the package
+          // We should warn the user, but not fail the build
+          const pathWarnedPackages = warnedPackages.get(path) ?? [];
+          pathWarnedPackages.push(importer);
+          warnedPackages.set(path, pathWarnedPackages);
+
+          return { external: true };
+        }
+        // This is a normal package—don't treat it specially
+        return result;
+      },
+    );
+
+    /**
+     * If we are bundling a "Service Worker" formatted Worker, imports of external modules,
+     * which won't be inlined/bundled by esbuild, are invalid.
+     *
+     * This `onEnd()` handler will error if it identifies node.js external imports.
+     */
+    pluginBuild.onEnd(() => {
+      if (
+        pluginBuild.initialOptions.format === "iife" &&
+        warnedPackages.size > 0
+      ) {
+        const paths = new Intl.ListFormat("en-US").format(
+          Array.from(warnedPackages.keys())
+            .map((p) => `"${p}"`)
+            .sort(),
+        );
+        return {
+          errors: [
+            {
+              text: dedent`
+                Unexpected external import of ${paths}.
+                Your worker has no default export, which means it is assumed to be a Service Worker format Worker.
+                Did you mean to create a ES Module format Worker?
+                If so, try adding \`export default { ... }\` in your entry-point.
+                See https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/.
+              `,
+            },
+          ],
+        };
+      }
+    });
+
+    // Wait until the build finishes to log warnings, so that all files which import a package
+    // can be collated
+    pluginBuild.onEnd(() => {
+      if (mode !== "v1") {
+        warnedPackages.forEach((importers: string[], path: string) => {
+          logger.warn(
+            dedent`
+            The package "${path}" wasn't found on the file system but is built into node.
+            Your Worker may throw errors at runtime unless you enable the "nodejs_compat" compatibility flag. Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/ for more details. Imported from:
+            ${toList(importers, pluginBuild.initialOptions.absWorkingDir)}`,
+          );
+        });
+      }
+    });
+  },
+});
+
+function toList(items: string[], absWorkingDir: string | undefined): string {
+  return items
+    .map((i) => ` - ${chalk.blue(relative(absWorkingDir ?? "/", i))}`)
+    .join("\n");
+}

package/src/cloudflare/cloudflare-env-proxy.ts

@@ -31,7 +31,7 @@ export const getPlatformProxyOptions = (
         };
   if (!persist) {
     const message =
-      "[Alchemy] Persistence for local bindings is disabled. Some bindings may not work as expected. To enable, remove the \`persist\` option from getPlatformProxyOptions.";
+      "[Alchemy] Persistence for local bindings is disabled. Some bindings may not work as expected. To enable, remove the `persist` option from getPlatformProxyOptions.";
     if (!warned.has(message)) {
       console.warn(message);
       warned.add(message);

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

@@ -4,4 +4,4 @@
 /**
  * The default Cloudflare Workers compatibility date, set based on the latest workerd release at the time of build.
  */
-export const DEFAULT_COMPATIBILITY_DATE = "2025-08-23";
+export const DEFAULT_COMPATIBILITY_DATE = "2025-08-26";

package/src/cloudflare/d1-local-migrations.ts

@@ -20,8 +20,8 @@ export const applyLocalD1Migrations = async (
   });
   try {
     await miniflare.ready;
-    const db = await miniflare.getD1Database("DB");
-    const session = db.withSession("first-primary");
+    const db: D1Database = await miniflare.getD1Database("DB");
+    const session: D1DatabaseSession = db.withSession("first-primary");
     await session
       .prepare(
         `CREATE TABLE IF NOT EXISTS ${options.migrationsTable} (

package/src/cloudflare/durable-object-namespace.ts

@@ -19,7 +19,7 @@ export type DurableObjectNamespace<T = any> = {
   environment?: string;
   sqlite?: boolean;
   namespaceId?: string;
-  // @ts-ignore - phantom type
+  /** @internal */
   __service__: T;
 };
 

package/src/cloudflare/hyperdrive.ts

@@ -537,7 +537,7 @@ const normalizePort = (
     return port;
   }
   if (port) {
-    return Number.parseInt(port);
+    return Number.parseInt(port, 10);
   }
   return scheme === "postgres" ? 5432 : 3306;
 };

package/src/cloudflare/website.ts

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { alchemy } from "../alchemy.ts";
 import { Exec } from "../os/index.ts";
 import { Scope } from "../scope.ts";
 import { isSecret } from "../secret.ts";
@@ -255,101 +254,101 @@ export async function Website<B extends Bindings>(
     entrypoint: path.relative(paths.cwd, paths.entrypoint),
   } as WorkerProps<B> & { name: string };
 
-  return await alchemy.run(id, { parent: Scope.current }, async (scope) => {
-    if (!workerProps.entrypoint) {
-      await fs.mkdir(path.dirname(paths.entrypoint), { recursive: true });
-      const content =
-        script ??
-        dedent`
-        export default {
-            async fetch(request, env) {
-                return new Response("Not Found", { status: 404 });
-            },
-        };`;
-      await fs.writeFile(paths.entrypoint, content);
-    }
+  if (!workerProps.entrypoint) {
+    await fs.mkdir(path.dirname(paths.entrypoint), { recursive: true });
+    const content =
+      script ??
+      dedent`
+      export default {
+          async fetch(request, env) {
+              return new Response("Not Found", { status: 404 });
+          },
+      };`;
+    await fs.writeFile(paths.entrypoint, content);
+  }
 
-    await writeMiniflareSymlink(paths.cwd);
+  await writeMiniflareSymlink(paths.cwd);
 
-    await WranglerJson("wrangler.jsonc", {
-      path: path.relative(paths.cwd, paths.wrangler.path),
-      worker,
-      assets: {
-        binding: "ASSETS",
-        directory: path.relative(paths.cwd, paths.assets),
-      },
-      main: path.relative(paths.cwd, paths.wrangler.main),
-      secrets,
-      transform: {
-        wrangler: props.wrangler?.transform,
-      },
-    });
+  await WranglerJson({
+    path: path.relative(paths.cwd, paths.wrangler.path),
+    worker,
+    assets: {
+      binding: "ASSETS",
+      directory: path.relative(paths.cwd, paths.assets),
+    },
+    main: path.relative(paths.cwd, paths.wrangler.main),
+    secrets,
+    transform: {
+      wrangler: props.wrangler?.transform,
+    },
+  });
 
-    if (build && !scope.local) {
-      await Exec("build", {
-        cwd: path.relative(process.cwd(), paths.cwd),
-        command: build.command,
-        env: {
-          ...env,
-          ...(typeof build === "object" ? build.env : {}),
-          NODE_ENV: "production",
-        },
-        memoize: typeof build === "object" ? build.memoize : undefined,
-      });
-    }
+  const scope = Scope.current;
 
-    let url: string | undefined;
-    if (dev && scope.local) {
-      url = await scope.spawn(name, {
-        cmd: typeof dev === "string" ? dev : dev.command,
-        cwd: paths.cwd,
-        extract: (line) => {
-          const URL_REGEX =
-            /http:\/\/(localhost|0\.0\.0\.0|127\.0\.0\.1|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}):\d+\/?/;
-          const match = line
-            .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")
-            .match(URL_REGEX);
-          if (match) {
-            return match[0];
-          }
-        },
-        env: {
-          ...Object.fromEntries(
-            Object.entries(env ?? {}).flatMap(([key, value]) => {
-              if (isSecret(value)) {
-                return [[key, value.unencrypted]];
-              }
-              if (typeof value === "string") {
-                return [[key, value]];
-              }
-              return [];
-            }),
-          ),
-          ...(typeof dev === "object" ? dev.env : {}),
-          FORCE_COLOR: "1",
-          ...process.env,
-          // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
-          // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
-          NODE_ENV: "development",
-        },
-      });
-    }
+  if (build && !scope.local) {
+    await Exec(`${id}-build`, {
+      cwd: path.relative(process.cwd(), paths.cwd),
+      command: build.command,
+      env: {
+        ...env,
+        ...(typeof build === "object" ? build.env : {}),
+        NODE_ENV: "production",
+      },
+      memoize: typeof build === "object" ? build.memoize : undefined,
+    });
+  }
 
-    return (await Worker("worker", {
-      ...worker,
-      bindings: {
-        ...worker.bindings,
-        ...(!scope.local
-          ? {
-              ASSETS: await Assets("assets", {
-                path: path.relative(process.cwd(), paths.assets),
-              }),
+  let url: string | undefined;
+  if (dev && scope.local) {
+    url = await scope.spawn(name, {
+      cmd: typeof dev === "string" ? dev : dev.command,
+      cwd: paths.cwd,
+      extract: (line) => {
+        const URL_REGEX =
+          /http:\/\/(localhost|0\.0\.0\.0|127\.0\.0\.1|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}):\d+\/?/;
+        const match = line
+          .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")
+          .match(URL_REGEX);
+        if (match) {
+          return match[0];
+        }
+      },
+      env: {
+        ...Object.fromEntries(
+          Object.entries(env ?? {}).flatMap(([key, value]) => {
+            if (isSecret(value)) {
+              return [[key, value.unencrypted]];
+            }
+            if (typeof value === "string") {
+              return [[key, value]];
             }
-          : {}),
+            return [];
+          }),
+        ),
+        ...(typeof dev === "object" ? dev.env : {}),
+        FORCE_COLOR: "1",
+        ...process.env,
+        // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
+        // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
+        NODE_ENV: "development",
       },
-      dev: url ? { url } : undefined,
-    })) as Website<B>;
-  });
+    });
+  }
+
+  return (await Worker(id, {
+    ...worker,
+    bindings: {
+      ...worker.bindings,
+      ...(!scope.local
+        ? {
+            ASSETS: await Assets("assets", {
+              path: path.relative(process.cwd(), paths.assets),
+            }),
+          }
+        : {}),
+    },
+    dev: url ? { url } : undefined,
+  })) as Website<B>;
 }
 
 async function writeMiniflareSymlink(cwd: string) {

package/src/cloudflare/worker-bundle.ts

@@ -4,11 +4,12 @@ import { err, ok, type Result } from "neverthrow";
 import fs from "node:fs/promises";
 import path from "pathe";
 import { logger } from "../util/logger.ts";
-import { external, external_als } from "./bundle/externals.ts";
+import { cloudflareInternalPlugin } from "./bundle/cloudflare-internal.ts";
 import { esbuildPluginAlias } from "./bundle/plugin-alias.ts";
-import { esbuildPluginCompatWarning } from "./bundle/plugin-compat-warning.ts";
+import { esbuildPluginAsyncLocalStorage } from "./bundle/plugin-als-external.ts";
 import { createHotReloadPlugin } from "./bundle/plugin-hot-reload.ts";
 import { esbuildPluginHybridNodeCompat } from "./bundle/plugin-hybrid-node-compat.ts";
+import { esbuildPluginNodeCompatImports } from "./bundle/plugin-node-compat.ts";
 import { createWasmPlugin } from "./bundle/plugin-wasm.ts";
 import { validateNodeCompat } from "./bundle/validate-node-compat.ts";
 
@@ -76,6 +77,8 @@ export function normalizeWorkerBundle(props: {
             cwd: props.cwd,
             outdir: props.outdir,
             sourcemap: props.sourceMap !== false ? true : undefined,
+            compatibilityDate: props.compatibilityDate,
+            compatibilityFlags: props.compatibilityFlags,
             ...props.bundle,
           }),
     );
@@ -248,6 +251,8 @@ export namespace WorkerBundleSource {
     entrypoint: string;
     cwd: string;
     outdir: string;
+    compatibilityDate: string;
+    compatibilityFlags: string[];
   }
 
   export class ESBuild implements WorkerBundleSource {
@@ -328,6 +333,8 @@ export namespace WorkerBundleSource {
         nodeCompat,
         cwd,
         format,
+        compatibilityDate: _compatibilityDate,
+        compatibilityFlags: _compatibilityFlags,
         ...props
       } = this.props;
       return {
@@ -356,19 +363,49 @@ export namespace WorkerBundleSource {
         conditions: props.conditions ?? ["workerd", "worker", "browser"],
         plugins: [
           esbuildPluginAlias(props.alias ?? {}, this.props.cwd),
-          nodeCompat === "v2"
-            ? esbuildPluginHybridNodeCompat()
-            : esbuildPluginCompatWarning(nodeCompat ?? null),
+          cloudflareInternalPlugin,
+          ...this.getNodeJSCompatPlugins({
+            mode: nodeCompat,
+            compatibilityDate: this.props.compatibilityDate,
+            compatibilityFlags: this.props.compatibilityFlags,
+          }),
           ...(props.plugins ?? []),
           ...additionalPlugins,
         ],
-        external: [
-          ...(nodeCompat === "als" ? external_als : external),
-          ...(props.external ?? []),
-        ],
+        external: [...(props.external ?? [])],
       } satisfies esbuild.BuildOptions;
     }
 
+    /**
+     * Returns the list of ESBuild plugins to use for a given compat mode.
+     */
+    private getNodeJSCompatPlugins({
+      mode,
+      compatibilityDate,
+      compatibilityFlags,
+    }: {
+      mode: "als" | "v2" | null;
+      compatibilityDate?: string;
+      compatibilityFlags?: string[];
+    }): esbuild.Plugin[] {
+      switch (mode) {
+        case "als":
+          return [
+            esbuildPluginAsyncLocalStorage,
+            esbuildPluginNodeCompatImports(mode),
+          ];
+        case "v2":
+          return [
+            esbuildPluginHybridNodeCompat({
+              compatibilityDate,
+              compatibilityFlags,
+            }),
+          ];
+        case null:
+          return [esbuildPluginNodeCompatImports(mode)];
+      }
+    }
+
     private async formatBuildOutput(
       metafile: esbuild.Metafile,
     ): Promise<WorkerBundle> {

package/src/cloudflare/worker-metadata.ts

@@ -442,6 +442,8 @@ export async function prepareWorkerMetadata(
         type: "r2_bucket",
         name: bindingName,
         bucket_name: binding.name,
+        jurisdiction:
+          binding.jurisdiction === "default" ? undefined : binding.jurisdiction,
       });
     } else if (binding.type === "secrets_store_secret") {
       meta.bindings.push({
@@ -651,7 +653,7 @@ export function bumpMigrationTagVersion(tag?: string) {
     if (!tag.match(/^v\d+$/)) {
       throw new Error(`Invalid tag format: ${tag}. Expected format: v<number>`);
     }
-    return `v${Number.parseInt(tag.slice(1)) + 1}`;
+    return `v${Number.parseInt(tag.slice(1), 10) + 1}`;
   }
   return undefined;
 }