alchemy 0.46.1 → 0.48.0

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/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-15";
+export const BUILD_DATE = "2025-07-16";

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/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/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

@@ -6,6 +6,7 @@ import fs from "node:fs/promises";
 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 { memoize } from "../util/memoize.ts";
 import {
@@ -15,7 +16,6 @@ import {
   HTTPError,
   singleFlight,
 } from "../util/neverthrow.ts";
-import { createXdgAppPaths } from "../util/xdg-paths.ts";
 
 const CLIENT_ID = "54d11594-84e4-41aa-b438-e81b8fa78ee7";
 const REDIRECT_URI = "http://localhost:8976/oauth/callback";
@@ -70,7 +70,7 @@ export const getRefreshedWranglerConfig = singleFlight(() =>
 );
 
 const getWranglerConfigPath = memoize(async () => {
-  const xdgConfigDir = createXdgAppPaths(".wrangler").config();
+  const xdgConfigDir = xdgAppPaths(".wrangler").config();
   const legacyConfigDir = path.join(os.homedir(), ".wrangler");
   const configDir = (await fs
     .stat(legacyConfigDir)
@@ -92,12 +92,12 @@ const readWranglerConfig = () => {
       const config = toml.parse(text.replace(/\r\n/g, "\n"));
       assert(typeof config.oauth_token === "string");
       assert(typeof config.refresh_token === "string");
-      assert(config.expiration_time instanceof Date);
+      assert(!!config.expiration_time);
       assert(Array.isArray(config.scopes));
       return {
         oauth_token: config.oauth_token,
         refresh_token: config.refresh_token,
-        expiration_time: new Date(config.expiration_time),
+        expiration_time: new Date(config.expiration_time as any),
         scopes: config.scopes as string[],
       };
     }),
@@ -110,6 +110,7 @@ const writeWranglerConfig = (config: WranglerConfig) => {
   return ResultAsync.fromSafePromise(getWranglerConfigPath()).map(
     async (configPath) => {
       const toml = await import("@iarna/toml");
+      await fs.mkdir(path.dirname(configPath), { recursive: true });
       await fs.writeFile(
         configPath,
         toml.stringify({

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",
     },
   });
 }

package/src/cloudflare/website.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { alchemy } from "../alchemy.ts";
 import { Exec } from "../os/exec.ts";
 import { Scope } from "../scope.ts";
+import { detectPackageManager } from "../util/detect-package-manager.ts";
 import { Assets } from "./assets.ts";
 import type { Bindings } from "./bindings.ts";
 import {
@@ -100,7 +101,6 @@ export interface WebsiteProps<B extends Bindings>
    */
   dev?: {
     command: string;
-    url: string;
   };
 
   /**
@@ -123,6 +123,15 @@ export interface WebsiteProps<B extends Bindings>
   };
 }
 
+const packageManager = await detectPackageManager();
+const devCommand = {
+  npm: "npx vite dev",
+  bun: "bun vite dev",
+  pnpm: "pnpm vite dev",
+  yarn: "yarn vite dev",
+  deno: "deno task dev",
+}[packageManager];
+
 export type Website<B extends Bindings> = B extends { ASSETS: any }
   ? never
   : Worker<B & { ASSETS: Assets }>;
@@ -189,12 +198,9 @@ export default {
 };`,
         url: props.url ?? true,
         adopt: props.adopt ?? true,
-        dev: props.dev
-          ? {
-              command: props.dev.command,
-              url: props.dev.url,
-            }
-          : undefined,
+        dev: {
+          command: props.dev?.command ?? devCommand,
+        },
       } as WorkerProps<any> & { name: string };
 
       if (wrangler) {
@@ -216,7 +222,7 @@ export default {
         });
       }
 
-      const isDev = scope.dev && !!props.dev;
+      const isDev = scope.local;
 
       if (props.command && !isDev) {
         await Exec("build", {

package/src/cloudflare/worker-metadata.ts

@@ -197,6 +197,9 @@ export interface WorkerMetadata {
     suspended: boolean;
   }[];
   containers?: { class_name: string }[];
+  placement?: {
+    mode: "smart";
+  };
 }
 
 export async function prepareWorkerMetadata(
@@ -213,6 +216,9 @@ export async function prepareWorkerMetadata(
     };
     tags?: string[];
     unstable_cacheWorkerSettings?: boolean;
+    placement?: {
+      mode: "smart";
+    };
   },
 ): Promise<WorkerMetadata> {
   const oldSettings = await (props.unstable_cacheWorkerSettings
@@ -336,6 +342,7 @@ export async function prepareWorkerMetadata(
       transferred_classes: [],
       new_sqlite_classes: [],
     },
+    placement: props.placement,
   };
 
   const assetUploadResult = props.assetUploadResult;

package/src/cloudflare/worker.ts

@@ -1,13 +1,7 @@
 import type esbuild from "esbuild";
 import kleur from "kleur";
 import { spawn } from "node:child_process";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import fs from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import path from "pathe";
 import { BUILD_DATE } from "../build-date.ts";
@@ -18,7 +12,7 @@ import { getBindKey, tryGetBinding } from "../runtime/bind.ts";
 import { isRuntime } from "../runtime/global.ts";
 import { bootstrapPlugin } from "../runtime/plugin.ts";
 import { Scope } from "../scope.ts";
-import { Secret, secret } from "../secret.ts";
+import { Secret, isSecret, secret } from "../secret.ts";
 import { serializeScope } from "../serde.ts";
 import type { type } from "../type.ts";
 import { DeferredPromise } from "../util/deferred-promise.ts";
@@ -92,6 +86,7 @@ import { Workflow, isWorkflow, upsertWorkflow } from "./workflow.ts";
 // Previous versions of `Worker` used the `Bundle` resource.
 // This import is here to avoid errors when destroying the `Bundle` resource.
 import "../esbuild/bundle.ts";
+import { exists } from "../util/exists.ts";
 
 /**
  * Configuration options for static assets
@@ -181,6 +176,8 @@ export interface BaseWorkerProps<
    * Environment variables to attach to the worker
    *
    * These will be converted to plain_text bindings
+   *
+   * @deprecated - use `bindings` instead
    */
   env?: {
     [key: string]: string;
@@ -351,7 +348,6 @@ export interface BaseWorkerProps<
    * the worker will be emulated locally and available at a randomly selected port.
    */
   dev?:
-    | boolean
     | {
         /**
          * Port to use for local development
@@ -363,12 +359,35 @@ export interface BaseWorkerProps<
          * @default false
          */
         remote?: boolean;
+        /** @internal */
+        command?: undefined;
       }
     | {
         command: string;
-        url: string;
         cwd?: string;
+        /** @internal */
+        port?: undefined;
+        /** @internal */
+        remote?: undefined;
       };
+
+  /**
+   * Smart placement configuration for the worker.
+   *
+   * Controls how Cloudflare places the worker across its network for optimal performance.
+   *
+   * When omitted, smart placement is disabled (default behavior).
+   */
+  placement?: {
+    /**
+     * The placement mode for the worker.
+     *
+     * - "smart": Automatically optimize placement based on performance metrics
+     *
+     * @default undefined (smart placement disabled)
+     */
+    mode: "smart";
+  };
 }
 
 export interface InlineWorkerProps<
@@ -563,6 +582,13 @@ export type Worker<
      * Version label for this worker deployment
      */
     version?: string;
+
+    /**
+     * Smart placement configuration for the worker
+     */
+    placement?: {
+      mode: "smart";
+    };
   };
 
 /**
@@ -1020,8 +1046,6 @@ export const _Worker = Resource(
         ? props.namespace
         : props.namespace?.namespaceName;
 
-    const dev = normalizeDev(this, props.dev);
-
     const [bundle, error] = wrap(() =>
       normalizeWorkerBundle({
         entrypoint: props.entrypoint,
@@ -1040,34 +1064,45 @@ export const _Worker = Resource(
       }),
     );
 
-    if (dev.local) {
+    // run locally if
+    const local = this.scope.local && !props.dev?.remote;
+    const watch = this.scope.watch;
+
+    if (local) {
       let url: string | undefined;
       if (error) {
         throw error;
       }
 
-      switch (dev.type) {
-        case "command":
-          createDevCommand({
-            id,
-            command: dev.command,
-            cwd: dev.cwd ?? props.cwd ?? process.cwd(),
-            env: props.env ?? {},
-          });
-          url = dev.url;
-          break;
-        case "miniflare": {
-          url = await createMiniflare({
-            id,
-            workerName,
-            compatibilityDate,
-            compatibilityFlags,
-            bindings: props.bindings,
-            bundle,
-            port: dev.port,
-          });
-          break;
-        }
+      if (props.dev?.command) {
+        const { url: commandUrl } = await createDevCommand({
+          id,
+          command: props.dev.command,
+          cwd: props.dev.cwd || props.cwd || process.cwd(),
+          env: {
+            ...props.env,
+            ...Object.fromEntries(
+              Object.entries(props.bindings ?? {}).flatMap(([key, value]) =>
+                typeof value === "string"
+                  ? [[key, value]]
+                  : isSecret(value)
+                    ? [[key, value.unencrypted]]
+                    : [],
+              ),
+            ),
+          },
+        });
+        url = commandUrl;
+      } else {
+        url = await createMiniflare({
+          id,
+          workerName,
+          compatibilityDate,
+          compatibilityFlags,
+          bindings: props.bindings,
+          bundle,
+          port: props.dev?.port,
+        });
       }
 
       return this({
@@ -1091,6 +1126,8 @@ export const _Worker = Resource(
         assets: props.assets,
         // Include cron triggers in the output
         crons: props.crons,
+        // Include placement configuration in the output
+        placement: props.placement,
         // phantom property
         Env: undefined!,
       } as unknown as Worker<B>);
@@ -1189,7 +1226,7 @@ export const _Worker = Resource(
     }
 
     let putWorkerResult: PutWorkerResult;
-    if (dev.type === "remote") {
+    if (watch) {
       // todo(john): clean this up and add log tail
       const controller = new AbortController();
       cleanups.push(() => controller.abort());
@@ -1383,6 +1420,8 @@ export const _Worker = Resource(
       namespace: props.namespace,
       // Include version information in the output
       version: props.version,
+      // Include placement configuration in the output
+      placement: props.placement,
       // phantom property
       Env: undefined!,
     } as unknown as Worker<B>);
@@ -1405,57 +1444,6 @@ process.on("SIGINT", async () => {
   process.exit(0);
 });
 
-type Dev =
-  | {
-      type: "none";
-      local: false;
-    }
-  | {
-      type: "miniflare";
-      port?: number;
-      local: true;
-    }
-  | {
-      type: "command";
-      command: string;
-      url: string;
-      cwd?: string;
-      local: true;
-    }
-  | {
-      type: "remote";
-      local: false;
-    };
-
-const normalizeDev = (ctx: Context<any>, dev: WorkerProps["dev"]): Dev => {
-  if (!ctx.scope.dev || ctx.phase === "delete" || dev === false) {
-    return {
-      type: "none",
-      local: false,
-    };
-  }
-  const devObj = dev === true ? {} : (dev ?? {});
-  if ("command" in devObj) {
-    // Commands are always local
-    return {
-      type: "command",
-      ...devObj,
-      local: true,
-    };
-  }
-  if (devObj.remote === false || ctx.scope.dev === "prefer-local") {
-    return {
-      type: "miniflare",
-      port: devObj.port,
-      local: true,
-    };
-  }
-  return {
-    type: "remote",
-    local: false,
-  };
-};
-
 const assertUnique = <T, Key extends keyof T>(
   inputs: T[],
   key: Key,
@@ -1827,15 +1815,15 @@ async function createMiniflare(props: {
   return await startPromise.value;
 }
 
-function createDevCommand(props: {
+async function createDevCommand(props: {
   id: string;
   command: string;
   cwd: string;
   env: Record<string, string>;
-}) {
+}): Promise<{ url: string }> {
   const persistFile = path.join(process.cwd(), ".alchemy", `${props.id}.pid`);
-  if (existsSync(persistFile)) {
-    const pid = Number.parseInt(readFileSync(persistFile, "utf8"));
+  if (await exists(persistFile)) {
+    const pid = Number.parseInt(await fs.readFile(persistFile, "utf8"));
     try {
       // Actually kill the process if it's alive
       process.kill(pid, "SIGTERM");
@@ -1843,12 +1831,20 @@ function createDevCommand(props: {
       // ignore
     }
     try {
-      unlinkSync(persistFile);
+      await fs.unlink(persistFile);
     } catch {
       // ignore
     }
   }
   const command = props.command.split(" ");
+  console.log({
+    command,
+    args: command.slice(1),
+    cwd: props.cwd,
+    env: {
+      ...props.env,
+    },
+  });
   const proc = spawn(command[0], command.slice(1), {
     cwd: props.cwd,
     env: {
@@ -1859,21 +1855,61 @@ function createDevCommand(props: {
         ".alchemy",
         "miniflare",
       ),
+      // Force colors in the child process since we're piping output
+      // FORCE_COLOR: "1",
     },
-    stdio: ["inherit", "inherit", "inherit"],
+    stdio: ["inherit", "pipe", "pipe"],
   });
-  cleanups.push(() => {
-    try {
-      unlinkSync(persistFile);
-    } catch {
-      // ignore
-    }
-    proc.kill();
+  const { url } = await new Promise<{ url: string }>((resolve, reject) => {
+    let urlFound = false;
+    let stdout = "";
+    let stderr = "";
+    const urlRegex =
+      /http:\/\/(?:(?:localhost|0\.0\.0\.0|127\.0\.0\.1)|(?:\d{1,3}\.){3}\d{1,3}):\d+(?:\/)?/;
+
+    const parseOutput = (data: string) => {
+      if (!urlFound) {
+        const match = data.match(urlRegex);
+        if (match) {
+          urlFound = true;
+          resolve({ url: match[0] });
+        }
+      }
+    };
+
+    // Handle stdout - parse for URL and write through with colors preserved
+    proc.stdout?.on("data", (data) => {
+      parseOutput(
+        (stdout += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
+      );
+      process.stdout.write(data);
+    });
+
+    proc.stderr?.on("data", (data) => {
+      parseOutput(
+        (stderr += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
+      );
+      process.stderr.write(data);
+    });
+
+    proc.on("error", (error) => {
+      reject(error);
+    });
+
+    cleanups.push(async () => {
+      try {
+        await fs.unlink(persistFile);
+      } catch {
+        // ignore
+      }
+      proc.kill();
+    });
   });
   if (proc.pid) {
-    mkdirSync(path.dirname(persistFile), { recursive: true });
-    writeFileSync(persistFile, proc.pid.toString());
+    await fs.mkdir(path.dirname(persistFile), { recursive: true });
+    await fs.writeFile(persistFile, proc.pid.toString());
   }
+  return { url };
 }
 
 type PutWorkerOptions = Omit<WorkerProps, "entrypoint"> & {