alchemy 2.0.0-beta.2 → 2.0.0-beta.4

package/src/Cloudflare/Website/StaticSite.ts

@@ -3,10 +3,17 @@ import { Command, type CommandProps } from "../../Build/Command.ts";
 import type { InputProps } from "../../Input.ts";
 import * as Namespace from "../../Namespace.ts";
 import type { AssetsConfig } from "../Workers/Assets.ts";
-import { Worker, type WorkerProps } from "../Workers/Worker.ts";
+import {
+  Worker,
+  type WorkerAssetsConfig,
+  type WorkerBindingProps,
+  type WorkerProps,
+} from "../Workers/Worker.ts";
 
-export interface StaticSiteProps
-  extends Omit<WorkerProps, "assets">, Omit<CommandProps, "env"> {
+export interface StaticSiteProps<Bindings extends WorkerBindingProps = {}>
+  extends
+    Omit<WorkerProps<Bindings, WorkerAssetsConfig>, "assets">,
+    Omit<CommandProps, "env"> {
   /**
    * Optional configuration for static asset routing behavior.
    * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
@@ -19,19 +26,98 @@ export interface StaticSiteProps
 
 export type StaticSite = ReturnType<typeof StaticSite>;
 
-export const StaticSite = (id: string, props: InputProps<StaticSiteProps>) =>
+/**
+ * A Cloudflare Worker that serves static assets built by a shell command.
+ *
+ * `StaticSite` runs a build command (e.g. `npm run build`), content-hashes
+ * the output directory, and deploys the result as a Cloudflare Worker with
+ * static assets. Use this when your site has its own build step that
+ * produces a directory of files — Hugo, Zola, Eleventy, or any custom
+ * pipeline.
+ *
+ * For Vite-based projects, prefer `Cloudflare.Vite` which handles
+ * building automatically.
+ *
+ * @resource
+ *
+ * @section Basic Usage
+ * Point `command` at your build script and `outdir` at where it writes
+ * output. Alchemy runs the command, hashes the output, and deploys it.
+ *
+ * @example Deploying a Hugo site
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("Blog", {
+ *   command: "hugo --minify",
+ *   outdir: "public",
+ * });
+ * ```
+ *
+ * @section Asset Configuration
+ * Use `assetsConfig` to control how Cloudflare handles routing for
+ * your static files — HTML handling, not-found behavior, etc.
+ *
+ * @example SPA-style routing
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("App", {
+ *   command: "npm run build",
+ *   outdir: "dist",
+ *   assetsConfig: {
+ *     htmlHandling: "auto-trailing-slash",
+ *     notFoundHandling: "single-page-application",
+ *   },
+ * });
+ * ```
+ *
+ * @section Custom Rebuild Scope
+ * By default, all non-gitignored files are hashed to decide whether
+ * the build should re-run. Use `memo` to narrow the scope.
+ *
+ * @example Narrowing the memo scope
+ * ```typescript
+ * const site = yield* Cloudflare.StaticSite("Docs", {
+ *   command: "npm run build",
+ *   outdir: "dist",
+ *   memo: {
+ *     include: ["content/**", "templates/**", "config.toml"],
+ *   },
+ * });
+ * ```
+ */
+export const StaticSite = <
+  const Bindings extends WorkerBindingProps = {},
+  Req = never,
+>(
+  id: string,
+  propsEff:
+    | InputProps<StaticSiteProps<Bindings>>
+    | Effect.Effect<InputProps<StaticSiteProps<Bindings>>, never, Req>,
+) =>
   Effect.gen(function* () {
-    // TODO(sam): local dev/hmr support?
-    const build = yield* Command("Build", props);
+    const props = Effect.isEffect(propsEff)
+      ? propsEff
+      : Effect.succeed(propsEff);
 
-    const worker = yield* Worker("Worker", {
-      ...props,
-      assets: {
-        path: build.outdir,
-        hash: build.hash,
-        config: props.assetsConfig,
-      },
-    });
+    // 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,
+      })),
+    );
 
-    return worker;
+    return yield* Worker<Bindings, WorkerAssetsConfig, Req>(
+      "Worker",
+      Effect.map(props, (props) => ({
+        ...props,
+        assets: {
+          path: build.outdir,
+          hash: build.hash,
+          config: props.assetsConfig,
+        },
+      })),
+    );
   }).pipe(Namespace.push(id));

package/src/Cloudflare/Website/Vite.ts

@@ -1,8 +1,16 @@
-import type { InputProps } from "../../Input.ts";
+import * as Effect from "effect/Effect";
 import type { MemoOptions } from "../../Build/Memo.ts";
-import { Worker, type WorkerProps } from "../Workers/Worker.ts";
+import type { InputProps } from "../../Input.ts";
+import {
+  Worker,
+  type WorkerAssetsConfig,
+  type WorkerBindingProps,
+  type WorkerProps,
+} from "../Workers/Worker.ts";
 
-export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
+export interface ViteProps<
+  Bindings extends WorkerBindingProps = {},
+> extends Omit<WorkerProps<Bindings>, "vite" | "main"> {
   /**
    * Root directory passed to Vite's `root` option.
    * Defaults to the current working directory (`process.cwd()`).
@@ -21,22 +29,31 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
 /**
  * A Cloudflare Worker deployed from a Vite project.
  *
- * `Vite` uses the Cloudflare Vite plugin to build both the server bundle and
- * client assets in a single `vite build` invocation — no manual `main`
- * entrypoint, build command, output directory, or Wrangler configuration
- * required.
+ * `Vite` uses the Cloudflare Vite plugin to build both the server bundle
+ * and client assets in a single `vite build` invocation — no manual
+ * `main` entrypoint, build command, output directory, or Wrangler
+ * configuration required.
  *
  * Input files are content-hashed (respecting `.gitignore` by default) so
  * unchanged projects skip the build and deploy entirely.
  *
+ * @resource
+ *
  * @section Deploying a Static Site
- * @example Basic Static Site
+ * For a pure static site (no SSR), a single call is all you need.
+ * Vite builds the project and Alchemy deploys the output as a
+ * Cloudflare Worker with static assets.
+ *
+ * @example Static Vite site
  * ```typescript
  * const site = yield* Cloudflare.Vite("Website");
  * ```
  *
- * @section Deploying a TanStack Start App
- * @example TanStack Start with SSR
+ * @section SSR Frameworks
+ * For SSR frameworks like TanStack Start, SolidStart, or Nuxt, enable
+ * `nodejs_compat` so the server bundle can use Node.js APIs.
+ *
+ * @example TanStack Start
  * ```typescript
  * const app = yield* Cloudflare.Vite("TanStackStart", {
  *   compatibility: {
@@ -45,8 +62,43 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
  * });
  * ```
  *
+ * @example SolidStart with worker-first routing
+ * ```typescript
+ * const app = yield* Cloudflare.Vite("SolidStart", {
+ *   compatibility: {
+ *     flags: ["nodejs_compat"],
+ *   },
+ *   assets: {
+ *     config: { runWorkerFirst: true },
+ *   },
+ * });
+ * ```
+ *
+ * @section Single-Page Applications
+ * For SPAs (React, Vue, etc.), configure asset handling so all
+ * routes fall back to `index.html`.
+ *
+ * @example Vue SPA
+ * ```typescript
+ * const app = yield* Cloudflare.Vite("Vue", {
+ *   compatibility: {
+ *     flags: ["nodejs_compat"],
+ *   },
+ *   assets: {
+ *     config: {
+ *       htmlHandling: "auto-trailing-slash",
+ *       notFoundHandling: "single-page-application",
+ *     },
+ *   },
+ * });
+ * ```
+ *
  * @section Custom Rebuild Scope
- * @example Narrow the Memo Scope
+ * By default, every non-gitignored file is hashed to decide whether
+ * a rebuild is needed. Use `memo` to narrow the scope when your
+ * project has large directories that don't affect the build output.
+ *
+ * @example Narrowing the memo scope
  * ```typescript
  * const site = yield* Cloudflare.Vite("Docs", {
  *   memo: {
@@ -55,12 +107,26 @@ export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
  * });
  * ```
  */
-export const Vite = (id: string, props: InputProps<ViteProps> = {}) =>
-  Worker(id, {
-    ...props,
-    main: undefined!,
-    vite: {
-      rootDir: props.rootDir,
-      memo: props.memo,
-    },
-  });
+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,
+        },
+      }),
+    ),
+  );

package/src/Cloudflare/Workers/Assets.ts

@@ -1,9 +1,7 @@
 import * as workers from "@distilled.cloud/cloudflare/workers";
-import * as Context from "effect/Context";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
-import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
 import type { ScopedPlanStatusSession } from "../../Cli/Cli.ts";
@@ -12,6 +10,13 @@ import { sha256, sha256Object } from "../../Util/index.ts";
 const MAX_ASSET_SIZE = 1024 * 1024 * 25; // 25MB
 const MAX_ASSET_COUNT = 20_000;
 
+export interface Assets {
+  kind: "Cloudflare.Workers.Assets";
+}
+
+export const isAssets = (value: any): value is Assets =>
+  value?.kind === "Cloudflare.Workers.Assets";
+
 export interface AssetsConfig extends Exclude<
   Exclude<workers.PutScriptRequest["metadata"]["assets"], undefined>["config"],
   undefined
@@ -31,27 +36,6 @@ export interface AssetsProps {
   config?: AssetsConfig;
 }
 
-export class Assets extends Context.Service<
-  Assets,
-  {
-    read(
-      directory: AssetsProps,
-    ): Effect.Effect<AssetReadResult, PlatformError | ValidationError>;
-    upload(
-      accountId: string,
-      workerName: string,
-      assets: AssetReadResult,
-      session: ScopedPlanStatusSession,
-    ): Effect.Effect<
-      { jwt: string | undefined },
-      | PlatformError
-      | ValidationError
-      | workers.CreateScriptAssetUploadError
-      | workers.CreateAssetUploadError
-    >;
-  }
->()("Cloudflare.Assets") {}
-
 export type ValidationError =
   | AssetTooLargeError
   | TooManyAssetsError
@@ -102,196 +86,175 @@ const getContentType = (name: string) => {
   return "application/octet-stream";
 };
 
-export const AssetsProvider = () =>
-  Layer.effect(
-    Assets,
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const createAssetUpload = yield* workers.createAssetUpload;
-      const createScriptAssetUpload = yield* workers.createScriptAssetUpload;
+const maybeReadString = Effect.fnUntraced(function* (file: string) {
+  const fs = yield* FileSystem.FileSystem;
+  return yield* fs.readFileString(file).pipe(
+    Effect.catchIf(
+      (error) =>
+        error._tag === "PlatformError" && error.reason._tag === "NotFound",
+      () => Effect.succeed(undefined),
+    ),
+  );
+});
 
-      const maybeReadString = Effect.fnUntraced(function* (file: string) {
-        return yield* fs.readFileString(file).pipe(
-          Effect.catchIf(
-            (error) =>
-              error._tag === "PlatformError" &&
-              error.reason._tag === "NotFound",
-            () => Effect.succeed(undefined),
-          ),
-        );
-      });
+const createIgnoreMatcher = Effect.fnUntraced(function* (patterns: string[]) {
+  const matcher = yield* Effect.promise(() =>
+    import("ignore").then(({ default: ignore }) => ignore().add(patterns)),
+  );
+  return (file: string) => matcher.ignores(file);
+});
 
-      const createIgnoreMatcher = Effect.fnUntraced(function* (
-        patterns: string[],
-      ) {
-        const matcher = yield* Effect.promise(() =>
-          import("ignore").then(({ default: ignore }) =>
-            ignore().add(patterns),
-          ),
-        );
-        return (file: string) => matcher.ignores(file);
-      });
+export const readAssets = Effect.fnUntraced(function* (props: AssetsProps) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const resolvedDirectory = path.resolve(props.directory);
+  const [files, ignore, _headers, _redirects] = yield* Effect.all([
+    fs.readDirectory(resolvedDirectory, { recursive: true }),
+    maybeReadString(path.join(resolvedDirectory, ".assetsignore")),
+    maybeReadString(path.join(resolvedDirectory, "_headers")),
+    maybeReadString(path.join(resolvedDirectory, "_redirects")),
+  ]);
+  const ignores = yield* createIgnoreMatcher([
+    ".assetsignore",
+    "_headers",
+    "_redirects",
+    ...(ignore
+      ?.split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0 && !line.startsWith("#")) ?? []),
+  ]);
+  const manifest = new Map<string, { hash: string; size: number }>();
+  let count = 0;
+  yield* Effect.forEach(
+    files,
+    Effect.fnUntraced(function* (name) {
+      if (ignores(name)) {
+        return;
+      }
+      const file = path.join(resolvedDirectory, name);
+      const stat = yield* fs.stat(file);
+      if (stat.type !== "File") {
+        return;
+      }
+      const size = Number(stat.size);
+      if (size > MAX_ASSET_SIZE) {
+        return yield* new AssetTooLargeError({
+          message: `Asset ${name} is too large (the maximum size is ${MAX_ASSET_SIZE / 1024 / 1024} MB; this asset is ${size / 1024 / 1024} MB)`,
+          name,
+          size,
+        });
+      }
+      const hash = yield* fs.readFile(file).pipe(
+        Effect.flatMap(sha256),
+        Effect.map((hash) => hash.slice(0, 32)),
+      );
+      count++;
+      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,
+          count,
+        });
+      }
+      manifest.set(
+        (name.startsWith("/") ? name : `/${name}`).replaceAll("\\", "/"),
+        {
+          hash,
+          size,
+        },
+      );
+    }),
+  );
+  const result = {
+    directory: props.directory,
+    config: props.config,
+    manifest: Object.fromEntries(
+      Array.from(manifest.entries()).sort((a, b) => a[0].localeCompare(b[0])),
+    ),
+    _headers,
+    _redirects,
+  };
+  return {
+    ...result,
+    hash: yield* sha256Object(result),
+  };
+});
 
-      return {
-        read: Effect.fnUntraced(function* (props: AssetsProps) {
-          const resolvedDirectory = path.resolve(props.directory);
-          const [files, ignore, _headers, _redirects] = yield* Effect.all([
-            fs.readDirectory(resolvedDirectory, { recursive: true }),
-            maybeReadString(path.join(resolvedDirectory, ".assetsignore")),
-            maybeReadString(path.join(resolvedDirectory, "_headers")),
-            maybeReadString(path.join(resolvedDirectory, "_redirects")),
-          ]);
-          const ignores = yield* createIgnoreMatcher([
-            ".assetsignore",
-            "_headers",
-            "_redirects",
-            ...(ignore
-              ?.split("\n")
-              .map((line) => line.trim())
-              .filter((line) => line.length > 0 && !line.startsWith("#")) ??
-              []),
-          ]);
-          const manifest = new Map<string, { hash: string; size: number }>();
-          let count = 0;
-          yield* Effect.forEach(
-            files,
-            Effect.fnUntraced(function* (name) {
-              if (ignores(name)) {
-                return;
-              }
-              const file = path.join(resolvedDirectory, name);
-              const stat = yield* fs.stat(file);
-              if (stat.type !== "File") {
-                return;
-              }
-              const size = Number(stat.size);
-              if (size > MAX_ASSET_SIZE) {
-                return yield* new AssetTooLargeError({
-                  message: `Asset ${name} is too large (the maximum size is ${MAX_ASSET_SIZE / 1024 / 1024} MB; this asset is ${size / 1024 / 1024} MB)`,
-                  name,
-                  size,
-                });
-              }
-              const hash = yield* fs.readFile(file).pipe(
-                Effect.flatMap(sha256),
-                Effect.map((hash) => hash.slice(0, 32)),
-              );
-              count++;
-              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,
-                  count,
-                });
-              }
-              manifest.set(
-                (name.startsWith("/") ? name : `/${name}`).replaceAll(
-                  "\\",
-                  "/",
-                ),
-                {
-                  hash,
-                  size,
-                },
-              );
-            }),
-          );
-          const result = {
-            directory: props.directory,
-            config: props.config,
-            manifest: Object.fromEntries(
-              Array.from(manifest.entries()).sort((a, b) =>
-                a[0].localeCompare(b[0]),
-              ),
-            ),
-            _headers,
-            _redirects,
-          };
-          return {
-            ...result,
-            hash: yield* sha256Object(result),
-          };
-        }),
-        upload: Effect.fnUntraced(function* (
-          accountId: string,
-          workerName: string,
-          assets: AssetReadResult,
-          { note }: ScopedPlanStatusSession,
-        ) {
-          yield* note("Checking assets...");
-          const session = yield* createScriptAssetUpload({
-            accountId,
-            scriptName: workerName,
-            manifest: assets.manifest,
-          });
-          if (!session.buckets?.length) {
-            return { jwt: session.jwt ?? undefined };
-          }
-          if (!session.jwt) {
-            return { jwt: undefined };
-          }
-          const uploadJwt = session.jwt;
-          let uploaded = 0;
-          const total = session.buckets.flat().length;
-          yield* note(`Uploaded ${uploaded} of ${total} assets...`);
-          const assetsByHash = new Map<string, string>();
-          for (const [name, { hash }] of Object.entries(assets.manifest)) {
-            assetsByHash.set(hash, name);
+export const uploadAssets = Effect.fnUntraced(function* (
+  accountId: string,
+  workerName: string,
+  assets: AssetReadResult,
+  { note }: ScopedPlanStatusSession,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const createScriptAssetUpload = yield* workers.createScriptAssetUpload;
+  const createAssetUpload = yield* workers.createAssetUpload;
+
+  yield* note("Checking assets...");
+  const session = yield* createScriptAssetUpload({
+    accountId,
+    scriptName: workerName,
+    manifest: assets.manifest,
+  });
+  if (!session.buckets?.length) {
+    return { jwt: session.jwt ?? undefined };
+  }
+  if (!session.jwt) {
+    return { jwt: undefined };
+  }
+  const uploadJwt = session.jwt;
+  let uploaded = 0;
+  const total = session.buckets.flat().length;
+  yield* note(`Uploaded ${uploaded} of ${total} assets...`);
+  const assetsByHash = new Map<string, string>();
+  for (const [name, { hash }] of Object.entries(assets.manifest)) {
+    assetsByHash.set(hash, name);
+  }
+  let jwt: string | undefined | null;
+  const directory = path.resolve(assets.directory);
+  yield* Effect.forEach(
+    session.buckets,
+    Effect.fnUntraced(function* (bucket) {
+      const body: Record<string, File> = {};
+      yield* Effect.forEach(
+        bucket,
+        Effect.fnUntraced(function* (hash) {
+          const name = assetsByHash.get(hash);
+          if (!name) {
+            return yield* new AssetNotFoundError({
+              message: `Asset ${hash} not found in manifest`,
+              hash,
+            });
           }
-          let jwt: string | undefined | null;
-          const directory = path.resolve(assets.directory);
-          yield* Effect.forEach(
-            session.buckets,
-            Effect.fnUntraced(function* (bucket) {
-              const body: Record<string, File> = {};
-              yield* Effect.forEach(
-                bucket,
-                Effect.fnUntraced(function* (hash) {
-                  const name = assetsByHash.get(hash);
-                  if (!name) {
-                    return yield* new AssetNotFoundError({
-                      message: `Asset ${hash} not found in manifest`,
-                      hash,
-                    });
-                  }
-                  const file = yield* fs
-                    .readFile(path.join(directory, name))
-                    .pipe(
-                      Effect.mapError(
-                        (error) =>
-                          new FailedToReadAssetError({
-                            message: `Failed to read asset ${name}: ${error.message}`,
-                            name,
-                            cause: error,
-                          }),
-                      ),
-                    );
-                  body[hash] = new File(
-                    [Buffer.from(file).toString("base64")],
-                    hash,
-                    {
-                      type: getContentType(name),
-                    },
-                  );
+          const file = yield* fs.readFile(path.join(directory, name)).pipe(
+            Effect.mapError(
+              (error) =>
+                new FailedToReadAssetError({
+                  message: `Failed to read asset ${name}: ${error.message}`,
+                  name,
+                  cause: error,
                 }),
-              );
-              const result = yield* createAssetUpload({
-                accountId,
-                base64: true,
-                body,
-                jwtToken: uploadJwt,
-              });
-
-              uploaded += bucket.length;
-              yield* note(`Uploaded ${uploaded} of ${total} assets...`);
-              if (result.jwt) {
-                jwt = result.jwt;
-              }
-            }),
+            ),
           );
-          return { jwt: jwt ?? undefined };
+          body[hash] = new File([Buffer.from(file).toString("base64")], hash, {
+            type: getContentType(name),
+          });
         }),
-      };
+      );
+      const result = yield* createAssetUpload({
+        accountId,
+        base64: true,
+        body,
+        jwtToken: uploadJwt,
+      });
+
+      uploaded += bucket.length;
+      yield* note(`Uploaded ${uploaded} of ${total} assets...`);
+      if (result.jwt) {
+        jwt = result.jwt;
+      }
     }),
   );
+  return { jwt: jwt ?? undefined };
+});