alchemy 2.0.0-beta.51 → 2.0.0-beta.52

package/src/Cloudflare/Website/StaticSite.ts

@@ -1,11 +1,17 @@
+import * as Output from "alchemy/Output";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import { AlchemyContext } from "../../AlchemyContext.ts";
 import { Command, type CommandProps } from "../../Build/Command.ts";
+import { DevServer } from "../../Build/DevServer.ts";
 import type { InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
+import { effectClass } from "../../Util/effect.ts";
+import type { Providers } from "../Providers.ts";
 import type { AssetsConfig } from "../Workers/Assets.ts";
 import {
   Worker,
+  type NormalizedBindings,
   type WorkerAssetsConfig,
   type WorkerBindingProps,
   type WorkerProps,
@@ -19,13 +25,48 @@ export interface StaticSiteProps<Bindings extends WorkerBindingProps = {}>
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
    */
-  assetsConfig?: AssetsConfig;
+
+  assets?: AssetsConfig;
+  /**
+   * Local dev configuration. When `alchemy dev` runs, the build command is
+   * skipped and `command` is spawned as a long-lived child process tied to
+   * the stack's scope. Alchemy does not proxy or interpret the process —
+   * the dev server's own URL (e.g. `http://localhost:5173`) is what you
+   * open in the browser.
+   *
+   * @example
+   * ```typescript
+   * Cloudflare.StaticSite("App", {
+   *   command: "npm run build",
+   *   outdir: "dist",
+   *   main: "./src/worker.ts",
+   *   dev: { command: "npm run dev" },
+   * });
+   * ```
+   */
   dev?: {
+    /**
+     * Shell command to run as the local dev server (e.g. `npm run dev`).
+     */
     command: string;
+    /**
+     * Working directory for {@link command}. Defaults to {@link CommandProps.cwd}
+     * (the build command's `cwd`), or `process.cwd()` if neither is set.
+     */
+    cwd?: string;
+    /**
+     * Override for the `url` output if alchemy fails to detect it from the stdout of the dev command
+     */
+    url?: string;
   };
 }
 
-export type StaticSite = ReturnType<typeof StaticSite>;
+type StaticSiteWorker<Bindings extends WorkerBindingProps> = Worker<{
+  [binding in keyof NormalizedBindings<
+    Bindings,
+    WorkerAssetsConfig
+  >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+}>;
 
 /**
  * A Cloudflare Worker that serves static assets built by a shell command.
@@ -68,7 +109,7 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  * ```
  *
  * @section Asset Configuration
- * Use `assetsConfig` to control how Cloudflare handles routing for
+ * Use `assets` to control how Cloudflare handles routing for
  * your static files — HTML handling, not-found behavior, etc.
  *
  * @example SPA-style routing
@@ -77,7 +118,7 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  *   command: "npm run build",
  *   outdir: "dist",
  *   main: "./src/worker.ts",
- *   assetsConfig: {
+ *   assets: {
  *     htmlHandling: "auto-trailing-slash",
  *     notFoundHandling: "single-page-application",
  *   },
@@ -113,54 +154,126 @@ export type StaticSite = ReturnType<typeof StaticSite>;
  *   },
  * });
  * ```
+ *
+ * @section Class Form
+ * Calling `StaticSite` with no arguments returns a constructor you can
+ * `extend` to declare the Worker as a named class. The class is both
+ * an `Effect` you can `yield*` to deploy and a type you can reference
+ * elsewhere — useful when other resources need to bind to this Worker.
+ *
+ * @example Declaring a Worker class
+ * ```typescript
+ * class Blog extends Cloudflare.StaticSite<Blog>()("Blog", {
+ *   command: "hugo --minify",
+ *   outdir: "public",
+ *   main: "./src/worker.ts",
+ * }) {}
+ *
+ * const site = yield* Blog;
+ * ```
  */
-export const StaticSite = <
+export const StaticSite: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff:
+        | InputProps<StaticSiteProps<Bindings>, "dev">
+        | Effect.Effect<
+            InputProps<StaticSiteProps<Bindings>, "dev">,
+            never,
+            Req
+          >,
+    ): Effect.Effect<Self, never, Req | Providers> & {
+      new (): StaticSiteWorker<Bindings>;
+    };
+  };
+  <const Bindings extends WorkerBindingProps = {}, Req = never>(
+    id: string,
+    propsEff:
+      | InputProps<StaticSiteProps<Bindings>, "dev">
+      | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
+  ): Effect.Effect<StaticSiteWorker<Bindings>, never, Req | Providers>;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(makeStaticSite(id, propsEff))
+    : makeStaticSite(id, propsEff)) as any;
+
+const makeStaticSite = <
   const Bindings extends WorkerBindingProps = {},
   Req = never,
 >(
   id: string,
   propsEff:
-    | InputProps<StaticSiteProps<Bindings>>
-    | Effect.Effect<InputProps<StaticSiteProps<Bindings>>, never, Req>,
+    | InputProps<StaticSiteProps<Bindings>, "dev">
+    | Effect.Effect<InputProps<StaticSiteProps<Bindings>, "dev">, never, Req>,
 ) =>
   Effect.gen(function* () {
     const props = Effect.isEffect(propsEff)
       ? propsEff
       : Effect.succeed(propsEff);
+    const { dev: isDevPhase } = yield* AlchemyContext;
 
-    // TODO(sam): local dev/hmr support?
-    const build = yield* Command(
-      "Build",
-      Effect.map(props, (props) => ({
-        command: props.command,
-        cwd: props.cwd,
-        memo: props.memo,
-        outdir: props.outdir,
-        env: props.env
-          ? Object.fromEntries(
-              Object.entries(props.env).flatMap(([k, v]) => {
-                if (v === undefined) return [];
-                if (typeof v === "string" || Redacted.isRedacted(v))
-                  return [[k, v]];
-                return [[k, JSON.stringify(v)]];
-              }),
-            )
-          : undefined,
-      })),
-    );
+    return yield* Effect.gen(function* () {
+      const resolved = yield* props;
+      const useDevServer = isDevPhase && resolved.dev !== undefined;
 
-    return yield* Worker<Bindings, WorkerAssetsConfig, Req>(
-      "Worker",
-      Effect.map(props, (props) => ({
-        ...props,
-        assets: {
-          path: build.outdir,
-          hash: build.hash,
-          config: props.assetsConfig,
-        },
-        // Omit the dev command from WorkerProps since it's different from WorkerProps["dev"].
-        // TODO: we'll need to update this when we add local dev support for StaticSite.
-        dev: undefined,
-      })),
-    );
+      // In dev mode with a dev.command, declare a DevCommand resource so
+      // the sidecar owns the process lifecycle (survives user-code HMR),
+      // skip the build, and tell Worker not to start a local instance.
+      let devUrl = yield* useDevServer
+        ? DevServer("Dev", {
+            command: resolved.dev!.command,
+            cwd:
+              resolved.dev!.cwd ??
+              (typeof resolved.cwd === "string" ? resolved.cwd : undefined),
+          }).pipe(
+            Effect.map((d) =>
+              Output.map(d.url, (url) => url ?? resolved.dev?.url ?? false),
+            ),
+          )
+        : Effect.succeed(false as const);
+
+      const build = useDevServer
+        ? undefined
+        : yield* Command("Build", {
+            command: resolved.command,
+            cwd: resolved.cwd,
+            memo: resolved.memo,
+            outdir: resolved.outdir,
+            env: resolved.env
+              ? Object.fromEntries(
+                  Object.entries(resolved.env).flatMap(([k, v]) => {
+                    if (v === undefined) return [];
+                    if (typeof v === "string" || Redacted.isRedacted(v))
+                      return [[k, v]];
+                    return [[k, JSON.stringify(v)]];
+                  }),
+                )
+              : undefined,
+          });
+
+      // Pure-static sites don't need a custom Worker entrypoint —
+      // delegate every request straight to the ASSETS binding. Only
+      // injected when the user provided neither `main` nor `script`.
+      const fallbackScript =
+        resolved.main == null && resolved.script == null
+          ? `export default { fetch: (request, env) => env.ASSETS.fetch(request) };`
+          : undefined;
+
+      return yield* Worker<Bindings, WorkerAssetsConfig, Req>("Worker", {
+        ...resolved,
+        assets: build
+          ? {
+              directory: build.outdir,
+              hash: build.hash,
+              ...resolved.assets,
+            }
+          : undefined,
+        // Opt out of the local Worker in dev when the external DevCommand
+        // is serving the content. The Worker resource still exists in
+        // state with a stub Attributes shape.
+        dev: useDevServer ? devUrl : undefined,
+        script: fallbackScript ?? resolved.script,
+      });
+    });
   }).pipe(Namespace.push(id));

package/src/Cloudflare/Website/Vite.ts

@@ -1,16 +1,19 @@
 import * as Effect from "effect/Effect";
 import type { MemoOptions } from "../../Build/Memo.ts";
 import type { InputProps } from "../../Input.ts";
+import { effectClass } from "../../Util/effect.ts";
+import type { Providers } from "../Providers.ts";
+import type { AssetsConfig } from "../Workers/Assets.ts";
 import {
   Worker,
+  type NormalizedBindings,
   type WorkerAssetsConfig,
   type WorkerBindingProps,
   type WorkerProps,
 } from "../Workers/Worker.ts";
-
 export interface ViteProps<
   Bindings extends WorkerBindingProps = {},
-> extends Omit<WorkerProps<Bindings>, "vite" | "main"> {
+> extends Omit<WorkerProps<Bindings>, "vite" | "main" | "assets"> {
   /**
    * Root directory passed to Vite's `root` option.
    * Defaults to the current working directory (`process.cwd()`).
@@ -24,6 +27,11 @@ export interface ViteProps<
    * @see {@link MemoOptions}
    */
   memo?: MemoOptions;
+  /**
+   * Optional configuration for static asset routing behavior.
+   * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
+   */
+  assets?: AssetsConfig;
 }
 
 /**
@@ -106,27 +114,67 @@ export interface ViteProps<
  *   },
  * });
  * ```
+ *
+ * @section Class Form
+ * Calling `Vite` with no arguments returns a constructor you can
+ * `extend` to declare the Worker as a named class. The class is both
+ * an `Effect` you can `yield*` to deploy and a type you can reference
+ * elsewhere — useful when other resources need to bind to this Worker.
+ *
+ * @example Declaring a Worker class
+ * ```typescript
+ * class Website extends Cloudflare.Vite<Website>()("Website", {
+ *   compatibility: { flags: ["nodejs_compat"] },
+ * }) {}
+ *
+ * const site = yield* Website;
+ * ```
  */
-export const Vite = <
-  const Bindings extends WorkerBindingProps = {},
-  Req = never,
->(
-  id: string,
-  propsEff?:
-    | InputProps<ViteProps<Bindings>>
-    | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
-) =>
-  Worker<Bindings, WorkerAssetsConfig, Req>(
-    id,
-    Effect.map(
-      Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
-      (props) => ({
-        ...props,
-        main: undefined!,
-        vite: {
-          rootDir: props?.rootDir,
-          memo: props?.memo,
-        },
-      }),
-    ),
-  );
+export const Vite: {
+  <Self>(): {
+    <const Bindings extends WorkerBindingProps = {}, Req = never>(
+      id: string,
+      propsEff?:
+        | InputProps<ViteProps<Bindings>>
+        | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
+    ): Effect.Effect<Self, never, Req | Providers> & {
+      new (): Worker<{
+        [binding in keyof NormalizedBindings<
+          Bindings,
+          WorkerAssetsConfig
+        >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+      }>;
+    };
+  };
+  <const Bindings extends WorkerBindingProps = {}, Req = never>(
+    id: string,
+    propsEff?:
+      | InputProps<ViteProps<Bindings>>
+      | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>,
+  ): Effect.Effect<
+    Worker<{
+      [binding in keyof NormalizedBindings<
+        Bindings,
+        WorkerAssetsConfig
+      >]: NormalizedBindings<Bindings, WorkerAssetsConfig>[binding];
+    }>,
+    never,
+    Req | Providers
+  >;
+} = ((id?: any, propsEff?: any) =>
+  id === undefined
+    ? (id: string, propsEff: any) => effectClass(Vite(id, propsEff))
+    : Worker(
+        id,
+        Effect.map(
+          Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff),
+          (props) => ({
+            ...props,
+            main: undefined!,
+            vite: {
+              rootDir: props?.rootDir,
+              memo: props?.memo,
+            },
+          }),
+        ),
+      )) as any;

package/src/Cloudflare/Workers/Assets.ts

@@ -32,9 +32,8 @@ export interface AssetReadResult {
   hash: string;
 }
 
-export interface AssetsProps {
+export interface AssetsProps extends AssetsConfig {
   directory: string;
-  config?: AssetsConfig;
 }
 
 export type ValidationError =
@@ -103,10 +102,13 @@ const createIgnoreMatcher = (patterns: string[]) => {
   return (file: string) => matcher.ignores(file);
 };
 
-export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
+export const readAssets = Effect.fnUntraced(function* ({
+  directory,
+  ...config
+}: AssetsProps) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const resolvedDirectory = path.resolve(props.directory);
+  const resolvedDirectory = path.resolve(directory);
   const [files, ignore, _headers, _redirects] = yield* Effect.all([
     fs.readDirectory(resolvedDirectory, { recursive: true }),
     maybeReadString(path.join(resolvedDirectory, ".assetsignore")),
@@ -151,7 +153,7 @@ export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
       if (count > MAX_ASSET_COUNT) {
         return yield* new TooManyAssetsError({
           message: `Too many assets (the maximum count is ${MAX_ASSET_COUNT}; this directory has ${count} assets)`,
-          directory: props.directory,
+          directory,
           count,
         });
       }
@@ -176,14 +178,14 @@ export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
   // causes both unnecessary re-uploads and `NotFound` failures when
   // the previously-recorded path is gone.
   const hash = yield* sha256Object({
-    config: props.config,
+    config,
     manifest: sortedManifest,
     _headers,
     _redirects,
   });
   return {
-    directory: props.directory,
-    config: props.config,
+    directory,
+    config,
     manifest: sortedManifest,
     _headers,
     _redirects,

package/src/Cloudflare/Workers/DynamicWorkerLoader.ts

@@ -100,10 +100,10 @@ type BindEffect = ReturnType<typeof bindLoader>;
  * surrounding Worker and returns a {@link DynamicWorkerLoaderHandle} with
  * `.load()` — no separate `.bind(...)` step required.
  *
- * The divergence is achieved via `[Symbol.iterator]`: the object is not an
- * `Effect` (so `InferEnv` resolves it to the native
- * {@link DynamicWorkerLoaderBinding} in the `env` position), but it is iterable
- * as one when `yield*`-ed.
+ * The divergence is achieved via `[Symbol.iterator]`: the object is
+ * deliberately not an `Effect` (so `InferEnv` and the Worker `env` resolver
+ * keep it as the native {@link DynamicWorkerLoaderBinding} rather than
+ * `yield*`-ing it), but it is iterable as one when `yield*`-ed.
  */
 export interface DynamicWorkerLoader {
   kind: DynamicWorkerTypeId;

package/src/Cloudflare/Workers/InferEnv.ts

@@ -45,20 +45,22 @@ export type GetBindingType<T> =
                           : T extends Cloudflare.Images
                             ? ImagesBinding
                             : T extends Cloudflare.Browser
-                              ? Fetcher
+                              ? BrowserRun
                               : T extends Cloudflare.Hyperdrive
                                 ? Hyperdrive
-                                : T extends Cloudflare.DynamicWorkerLoader
-                                  ? Cloudflare.DynamicWorkerLoaderBinding
-                                  : T extends Cloudflare.DurableObjectNamespaceLike
-                                    ? DurableObjectNamespace<
-                                        Exclude<T["Shape"], undefined>
-                                      >
-                                    : T extends Redacted<any>
-                                      ? // redacteds are always stored as secret_text, so are always string
-                                        // we JSON.stringify when not a Redacted<string>
-                                        string
-                                      : T;
+                                : T extends Cloudflare.VersionMetadata
+                                  ? WorkerVersionMetadata
+                                  : T extends Cloudflare.DynamicWorkerLoader
+                                    ? Cloudflare.DynamicWorkerLoaderBinding
+                                    : T extends Cloudflare.DurableObjectNamespaceLike
+                                      ? DurableObjectNamespace<
+                                          Exclude<T["Shape"], undefined>
+                                        >
+                                      : T extends Redacted<any>
+                                        ? // redacteds are always stored as secret_text, so are always string
+                                          // we JSON.stringify when not a Redacted<string>
+                                          string
+                                        : T;
 
 /**
  * Cloudflare service-binding wire shape for an Effect-native Worker.

package/src/Cloudflare/Workers/LocalWorkerProvider.ts

@@ -66,6 +66,10 @@ import type { WorkerBinding } from "./WorkerBinding.ts";
 import { WorkerBundle, type WorkerBundleOptions } from "./WorkerBundle.ts";
 import { createWorkerName } from "./WorkerName.ts";
 
+type WorkerPropsWithDev = Omit<WorkerProps, "dev"> & {
+  dev: Exclude<WorkerProps["dev"], false | string>;
+};
+
 export class WorkerValidationError extends Schema.TaggedErrorClass<WorkerValidationError>()(
   "WorkerValidationError",
   {
@@ -227,7 +231,7 @@ export const LocalWorkerProvider = () =>
         bindings,
       }: {
         id: string;
-        props: WorkerProps;
+        props: WorkerPropsWithDev;
         bindings: ResourceBinding<Worker["Binding"]>[];
       }) {
         const name = yield* createWorkerName(id, props.name);
@@ -244,6 +248,7 @@ export const LocalWorkerProvider = () =>
               ? Text.local(key, unredacted)
               : Json.local(key, unredacted);
           }),
+          ...(props.assets || props.vite ? [Assets.local("ASSETS")] : []),
         ];
         const durableObjectNamespaces: Record<string, string> = {};
         const hyperdrives: Record<string, Required<HyperdriveOrigin>> = {};
@@ -257,11 +262,19 @@ export const LocalWorkerProvider = () =>
             ) {
               // Reuse the existing namespace id if it was provided, otherwise generate a new one.
               // `workerd` uses this for the object's storage path, so it must be safe to use as a file name.
-              durableObjectNamespaces[binding.className] =
+              const namespaceId =
                 binding.namespaceId ??
-                encodeURIComponent(`${id}-${binding.className}`);
+                encodeURIComponent(`${name}-${binding.className}`);
+              durableObjectNamespaces[binding.className] = namespaceId;
+              workerBindings.push(
+                yield* toRuntimeBinding({
+                  ...binding,
+                  namespaceId,
+                }),
+              );
+            } else {
+              workerBindings.push(yield* toRuntimeBinding(binding));
             }
-            workerBindings.push(yield* toRuntimeBinding(binding));
           }
           if (data.hyperdrives) {
             for (const [id, origin] of Object.entries(data.hyperdrives)) {
@@ -408,7 +421,7 @@ export const LocalWorkerProvider = () =>
 
       const runInstance = Effect.fn(function* (options: {
         id: string;
-        props: WorkerProps;
+        props: WorkerPropsWithDev;
         bindings: ResourceBinding<Worker["Binding"]>[];
       }) {
         const { props, bindings } = options;
@@ -450,7 +463,32 @@ export const LocalWorkerProvider = () =>
           };
         }),
         reconcile: Effect.fn(function* ({ id, news, bindings }) {
-          const options = { id, props: news, bindings };
+          // `dev: false` opts out of running a local Worker entirely —
+          // typically because an external dev process (DevCommand) is
+          // serving requests. Tear down any prior instance and return a
+          // stub Attributes; the resource exists in state but has no
+          // running workerd / proxy behind it.
+          if (news.dev === false || typeof news.dev === "string") {
+            const existing = instances.get(id);
+            if (existing) {
+              yield* Fiber.interrupt(existing.fiber);
+              yield* Scope.close(existing.scope, Exit.void);
+              instances.delete(id);
+            }
+            const name = yield* createWorkerName(id, news.name);
+            return {
+              workerId: name,
+              workerName: name,
+              logpush: undefined,
+              url: news.dev || undefined,
+              tags: [],
+              durableObjectNamespaces: {},
+              accountId,
+              domains: [],
+              crons: news.crons ?? [],
+            } satisfies Worker["Attributes"];
+          }
+          const options = { id, props: news as WorkerPropsWithDev, bindings };
           const hash = Hash.structure(options);
           const existing = instances.get(options.id);
           if (existing) {
@@ -526,6 +564,9 @@ const toRuntimeBinding = Effect.fnUntraced(function* (b: WorkerBinding) {
         binding: b.name,
         className: b.className,
         scriptName: b.scriptName,
+        uniqueKey:
+          b.namespaceId ??
+          encodeURIComponent(`${b.scriptName!}-${b.className}`),
       });
     case "hyperdrive":
       return Hyperdrive.local(b.name, b.id);
@@ -600,24 +641,24 @@ const toRuntimeAssets = (
     };
   }
   return {
-    directory: "directory" in assets ? assets.directory : assets.path,
-    headers: assets.config?.headers,
-    redirects: assets.config?.redirects,
+    directory: assets.directory,
+    headers: assets.headers,
+    redirects: assets.redirects,
     // Distilled widened generated string enums to open unions (`string & {}`);
     // the API only ever returns the known variants here.
-    htmlHandling: assets.config?.htmlHandling as
+    htmlHandling: assets.htmlHandling as
       | "none"
       | "auto-trailing-slash"
       | "force-trailing-slash"
       | "drop-trailing-slash"
       | undefined,
-    notFoundHandling: assets.config?.notFoundHandling as
+    notFoundHandling: assets.notFoundHandling as
       | "none"
       | "404-page"
       | "single-page-application"
       | undefined,
-    runWorkerFirst: assets.config?.runWorkerFirst,
-    serveDirectly: assets.config?.serveDirectly,
+    runWorkerFirst: assets.runWorkerFirst,
+    serveDirectly: assets.serveDirectly,
   };
 };