The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { InputProps } from "alchemy/Input"; |
| 2 | import { effectClass } from "alchemy/Util/effect"; |
| 3 | import * as Effect from "effect/Effect"; |
| 4 | import type { Providers } from "../Providers.ts"; |
| 5 | import type { AssetsConfig } from "../Workers/Assets.ts"; |
| 6 | import { |
| 7 | Worker, |
| 8 | type NormalizedBindings, |
| 9 | type ViteOptions, |
| 10 | type WorkerAssetsConfig, |
| 11 | type WorkerBindingProps, |
| 12 | type WorkerProps, |
| 13 | } from "../Workers/Worker.ts"; |
| 14 | |
| 15 | export interface FoldkitProps<Bindings extends WorkerBindingProps = {}> extends Omit< |
| 16 | WorkerProps<Bindings>, |
| 17 | "vite" | "main" | "assets" | "source" | "script" | "bundle" | "rules" |
| 18 | > { |
| 19 | /** |
| 20 | * Custom Worker entry for a client-only app. Relative paths resolve from |
| 21 | * {@link rootDir}; the Worker can serve client assets through `ASSETS`. |
| 22 | * Cannot be combined with Foldkit's `ssr.build`, which generates the |
| 23 | * Worker handler from the app's server entry. |
| 24 | */ |
| 25 | main?: string; |
| 26 | /** |
| 27 | * Foldkit project root directory, resolved from the working directory. |
| 28 | * @default process.cwd() |
| 29 | */ |
| 30 | rootDir?: string; |
| 31 | /** |
| 32 | * Controls which files are content-hashed to decide whether to rebuild. |
| 33 | * Defaults to non-gitignored project files and the nearest lockfile, with |
| 34 | * imported workspaces detected from the build. See {@link ViteOptions.memo}. |
| 35 | */ |
| 36 | memo?: ViteOptions["memo"]; |
| 37 | /** |
| 38 | * Overrides static asset routing defaults. Client-only apps use |
| 39 | * `notFoundHandling: "single-page-application"`. SSR and prerendered apps |
| 40 | * serve matching assets and send unmatched requests to Foldkit's handler. |
| 41 | * Explicit options take precedence over these defaults. |
| 42 | */ |
| 43 | assets?: AssetsConfig; |
| 44 | } |
| 45 | |
| 46 | /** |
| 47 | * A Cloudflare Worker deployed from a [Foldkit](https://foldkit.dev) app. |
| 48 | * |
| 49 | * Builds the project's Vite configuration and deploys its client assets |
| 50 | * and generated server handler. Configure rendering in the app's |
| 51 | * `foldkit(...)` plugin call; Alchemy derives asset routing from the |
| 52 | * plugin's completed build metadata. |
| 53 | * |
| 54 | * Input files are content-hashed (respecting `.gitignore` by default) so |
| 55 | * unchanged projects skip the build and deploy entirely. |
| 56 | * |
| 57 | * ### Deploying a Foldkit App |
| 58 | * The same declaration supports client-only, server-rendered, and |
| 59 | * prerendered apps. |
| 60 | * |
| 61 | * **Example:** Foldkit app |
| 62 | * ```typescript |
| 63 | * const site = yield* Cloudflare.Website.Foldkit("Website"); |
| 64 | * ``` |
| 65 | * |
| 66 | * **Example:** Foldkit project in a subdirectory |
| 67 | * ```typescript |
| 68 | * const site = yield* Cloudflare.Website.Foldkit("Website", { |
| 69 | * rootDir: "apps/web", |
| 70 | * }); |
| 71 | * ``` |
| 72 | * |
| 73 | * ### Server Rendering and Prerendering |
| 74 | * Enable `ssr.build` to generate the Worker handler. Foldkit manages the |
| 75 | * shared hydration identity for the client and server automatically. |
| 76 | * Requires `@foldkit/vite-plugin` 0.27.0 or newer and a compatible Foldkit |
| 77 | * version (0.167.0 or newer). Import CSS from the client entry and export |
| 78 | * `renderDocument = Server.renderDocument` alongside `renderPage` in the |
| 79 | * server entry. SSR/SSG documents are generated from code; no source index.html is needed. |
| 80 | * |
| 81 | * **Example:** vite.config.ts for a server-rendered app |
| 82 | * ```typescript |
| 83 | * import { foldkit } from "@foldkit/vite-plugin"; |
| 84 | * import { defineConfig } from "vite"; |
| 85 | * |
| 86 | * export default defineConfig({ |
| 87 | * plugins: [ |
| 88 | * foldkit({ |
| 89 | * ssr: { |
| 90 | * serverEntry: "/src/entry.server.ts", |
| 91 | * clientEntry: "/src/entry.ts", |
| 92 | * build: true, |
| 93 | * }, |
| 94 | * }), |
| 95 | * ], |
| 96 | * }); |
| 97 | * ``` |
| 98 | * |
| 99 | * **Example:** Prerendering the server entry's `prerenderPaths` |
| 100 | * ```typescript |
| 101 | * foldkit({ |
| 102 | * ssr: { |
| 103 | * serverEntry: "/src/entry.server.ts", |
| 104 | * clientEntry: "/src/entry.ts", |
| 105 | * build: { prerender: true }, |
| 106 | * }, |
| 107 | * }); |
| 108 | * ``` |
| 109 | * |
| 110 | * ### Asset Routing |
| 111 | * Use `assets` to override the rendering mode's defaults (see |
| 112 | * {@link FoldkitProps.assets}). |
| 113 | * |
| 114 | * **Example:** Client-only app with a custom 404 page |
| 115 | * ```typescript |
| 116 | * const site = yield* Cloudflare.Website.Foldkit("Website", { |
| 117 | * assets: { notFoundHandling: "404-page" }, |
| 118 | * }); |
| 119 | * ``` |
| 120 | * |
| 121 | * ### Custom Worker Entry |
| 122 | * For a client-only app with API routes or other Worker handlers, set |
| 123 | * `main` and route those requests through the Worker. Bindings in `env` |
| 124 | * are available to the Worker, not to browser code. |
| 125 | * |
| 126 | * **Example:** Custom Worker with a KV binding |
| 127 | * ```typescript |
| 128 | * const ticker = yield* Cloudflare.KV.Namespace("Ticker"); |
| 129 | * |
| 130 | * const site = yield* Cloudflare.Website.Foldkit("Platform", { |
| 131 | * main: "src/worker.ts", |
| 132 | * env: { TICKER: ticker }, |
| 133 | * assets: { runWorkerFirst: ["/api/*"] }, |
| 134 | * }); |
| 135 | * ``` |
| 136 | * |
| 137 | * ### Custom Rebuild Scope |
| 138 | * Narrow the files hashed for rebuilds while retaining the Vite config |
| 139 | * and lockfile as build inputs. |
| 140 | * |
| 141 | * **Example:** Narrowing the memo scope |
| 142 | * ```typescript |
| 143 | * const site = yield* Cloudflare.Website.Foldkit("Website", { |
| 144 | * memo: { |
| 145 | * include: [ |
| 146 | * "src/**", |
| 147 | * "public/**", |
| 148 | * "index.html", |
| 149 | * "vite.config.ts", |
| 150 | * "package.json", |
| 151 | * ], |
| 152 | * lockfile: true, |
| 153 | * }, |
| 154 | * }); |
| 155 | * ``` |
| 156 | * |
| 157 | * ### Class Form |
| 158 | * Use the class form when other resources need to reference the Worker. |
| 159 | * |
| 160 | * **Example:** Declaring a Worker class |
| 161 | * ```typescript |
| 162 | * class Website extends Cloudflare.Website.Foldkit<Website>()("Website") {} |
| 163 | * |
| 164 | * const site = yield* Website; |
| 165 | * ``` |
| 166 | * |
| 167 | * @resource |
| 168 | * @product Website |
| 169 | * @category Workers & Compute |
| 170 | */ |
| 171 | export const Foldkit: { |
| 172 | <Self>(): { |
| 173 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 174 | id: string, |
| 175 | propsEff?: |
| 176 | | InputProps<FoldkitProps<Bindings>> |
| 177 | | Effect.Effect<InputProps<FoldkitProps<Bindings>>, never, Req>, |
| 178 | ): Effect.Effect<Self, never, Req | Providers> & { |
| 179 | new (): Worker<{ |
| 180 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 181 | Bindings, |
| 182 | WorkerAssetsConfig |
| 183 | >[binding]; |
| 184 | }>; |
| 185 | }; |
| 186 | }; |
| 187 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 188 | id: string, |
| 189 | propsEff?: |
| 190 | | InputProps<FoldkitProps<Bindings>> |
| 191 | | Effect.Effect<InputProps<FoldkitProps<Bindings>>, never, Req>, |
| 192 | ): Effect.Effect< |
| 193 | Worker<{ |
| 194 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 195 | Bindings, |
| 196 | WorkerAssetsConfig |
| 197 | >[binding]; |
| 198 | }>, |
| 199 | never, |
| 200 | Req | Providers |
| 201 | >; |
| 202 | } = (<const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 203 | id?: string, |
| 204 | propsEff?: |
| 205 | | InputProps<FoldkitProps<Bindings>> |
| 206 | | Effect.Effect<InputProps<FoldkitProps<Bindings>>, never, Req>, |
| 207 | ) => |
| 208 | id === undefined |
| 209 | ? <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 210 | id: string, |
| 211 | propsEff?: |
| 212 | | InputProps<FoldkitProps<Bindings>> |
| 213 | | Effect.Effect<InputProps<FoldkitProps<Bindings>>, never, Req>, |
| 214 | ) => effectClass(Foldkit(id, propsEff)) |
| 215 | : Worker( |
| 216 | id, |
| 217 | Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => { |
| 218 | const { main, rootDir, memo, ...workerProps } = props ?? {}; |
| 219 | return { |
| 220 | ...workerProps, |
| 221 | vite: { |
| 222 | framework: "foldkit" as const, |
| 223 | main, |
| 224 | rootDir, |
| 225 | memo, |
| 226 | }, |
| 227 | }; |
| 228 | }), |
| 229 | )) as any; |