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 ViteProps<Bindings extends WorkerBindingProps = {}> |
| 16 | extends Omit<WorkerProps<Bindings>, "vite" | "main" | "assets" | "rules">, ViteOptions { |
| 17 | /** |
| 18 | * Optional configuration for static asset routing behavior. |
| 19 | * Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc. |
| 20 | */ |
| 21 | assets?: AssetsConfig; |
| 22 | } |
| 23 | |
| 24 | /** |
| 25 | * A Cloudflare Worker deployed from a Vite project. |
| 26 | * |
| 27 | * `Vite` uses the Cloudflare Vite plugin to build both the server bundle |
| 28 | * and client assets in a single `vite build` invocation — no manual |
| 29 | * `main` entrypoint, build command, output directory, or Wrangler |
| 30 | * configuration required. |
| 31 | * |
| 32 | * Input files are content-hashed (respecting `.gitignore` by default) so |
| 33 | * unchanged projects skip the build and deploy entirely. |
| 34 | * |
| 35 | * |
| 36 | * ### Deploying a Static Site |
| 37 | * For a pure static site (no SSR), a single call is all you need. |
| 38 | * Vite builds the project and Alchemy deploys the output as a |
| 39 | * Cloudflare Worker with static assets. |
| 40 | * |
| 41 | * **Example:** Static Vite site |
| 42 | * ```typescript |
| 43 | * const site = yield* Cloudflare.Website.Vite("Website"); |
| 44 | * ``` |
| 45 | * |
| 46 | * ### SSR Frameworks |
| 47 | * SSR frameworks like TanStack Start or SolidStart work with a single |
| 48 | * call — the `nodejs_compat` compatibility flag is enabled by default |
| 49 | * so the server bundle can use Node.js APIs. |
| 50 | * |
| 51 | * **Example:** TanStack Start |
| 52 | * ```typescript |
| 53 | * const app = yield* Cloudflare.Website.Vite("TanStackStart"); |
| 54 | * ``` |
| 55 | * |
| 56 | * **Example:** SolidStart with worker-first routing |
| 57 | * ```typescript |
| 58 | * const app = yield* Cloudflare.Website.Vite("SolidStart", { |
| 59 | * assets: { runWorkerFirst: true }, |
| 60 | * }); |
| 61 | * ``` |
| 62 | * |
| 63 | * **Example:** React Router |
| 64 | * React Router's server build (`virtual:react-router/server-build`) is a |
| 65 | * build manifest with no default export, so it cannot be deployed as the |
| 66 | * Worker entry directly. Point `main` at a module that wraps it with |
| 67 | * `createRequestHandler` (React Router's Cloudflare template ships this |
| 68 | * as `workers/app.ts`): |
| 69 | * ```typescript |
| 70 | * const app = yield* Cloudflare.Website.Vite("ReactRouter", { |
| 71 | * main: "workers/app.ts", |
| 72 | * }); |
| 73 | * ``` |
| 74 | * |
| 75 | * ### React Server Components |
| 76 | * Frameworks that emit more than one server environment (e.g. React |
| 77 | * Server Components, which split into an `rsc` environment and an `ssr` |
| 78 | * environment) need `viteEnvironments` to declare which environment |
| 79 | * produces the deployed Worker entry and which additional server |
| 80 | * environments to bundle alongside it. The `client` environment is |
| 81 | * always deployed as static assets. |
| 82 | * |
| 83 | * **Example:** React Router with RSC |
| 84 | * ```typescript |
| 85 | * const app = yield* Cloudflare.Website.Vite("ReactRouterRSC", { |
| 86 | * viteEnvironments: { |
| 87 | * entry: "rsc", |
| 88 | * children: ["ssr"], |
| 89 | * }, |
| 90 | * }); |
| 91 | * ``` |
| 92 | * |
| 93 | * ### Custom Worker Entry |
| 94 | * By default the deployed Worker entry is the server bundle the |
| 95 | * framework produces. When the Worker must export more than the |
| 96 | * framework's fetch handler — Durable Object classes, additional |
| 97 | * handlers — point `main` at your own module that wraps the framework |
| 98 | * handler and re-exports the extras. `main` takes precedence over any |
| 99 | * entry configured in the Vite config. |
| 100 | * |
| 101 | * **Example:** Custom entry hosting Durable Objects |
| 102 | * ```typescript |
| 103 | * const app = yield* Cloudflare.Website.Vite("App", { |
| 104 | * main: "worker/index.ts", |
| 105 | * viteEnvironments: { |
| 106 | * entry: "rsc", |
| 107 | * children: ["ssr"], |
| 108 | * }, |
| 109 | * }); |
| 110 | * ``` |
| 111 | * |
| 112 | * ### Single-Page Applications |
| 113 | * For SPAs (React, Vue, etc.), configure asset handling so unmatched |
| 114 | * routes fall back to `index.html` and the client router takes over. |
| 115 | * |
| 116 | * **Example:** Vue SPA |
| 117 | * ```typescript |
| 118 | * const app = yield* Cloudflare.Website.Vite("Vue", { |
| 119 | * assets: { |
| 120 | * notFoundHandling: "single-page-application", |
| 121 | * }, |
| 122 | * }); |
| 123 | * ``` |
| 124 | * |
| 125 | * **Example:** Foldkit |
| 126 | * [Foldkit](https://foldkit.dev) apps are Vite projects, so a single call |
| 127 | * deploys them — the Foldkit Vite plugin in the app's own `vite.config.ts` |
| 128 | * composes with the injected Cloudflare plugin, and with `ssr.build` set |
| 129 | * there its `fetch` handler is the server bundle this resource deploys, |
| 130 | * exactly as TanStack Start's is. A client-only Foldkit app wants |
| 131 | * `single-page-application` not-found handling so deep links boot it: |
| 132 | * ```typescript |
| 133 | * const app = yield* Cloudflare.Website.Vite("Foldkit", { |
| 134 | * assets: { |
| 135 | * notFoundHandling: "single-page-application", |
| 136 | * }, |
| 137 | * }); |
| 138 | * ``` |
| 139 | * {@link Foldkit | Cloudflare.Website.Foldkit} drives the same build and |
| 140 | * derives asset routing from Foldkit's completed build metadata. It also |
| 141 | * supplies SPA fallback for client-only apps. |
| 142 | * |
| 143 | * **Example:** Octane SPA |
| 144 | * A client-only [OctaneJS](https://octanejs.dev) app (no `octane.config.ts` |
| 145 | * routes) is a plain Vite SPA — the `octane()` compiler plugin in the app's |
| 146 | * own `vite.config.ts` composes with the injected Cloudflare plugin: |
| 147 | * ```typescript |
| 148 | * const app = yield* Cloudflare.Website.Vite("Octane", { |
| 149 | * assets: { |
| 150 | * notFoundHandling: "single-page-application", |
| 151 | * }, |
| 152 | * }); |
| 153 | * ``` |
| 154 | * Fullstack Octane apps (routes + SSR in `octane.config.ts`) run their own |
| 155 | * two-pass build through Octane's Cloudflare adapter — deploy those with |
| 156 | * `Cloudflare.Website.Octane` instead. |
| 157 | * |
| 158 | * ### Serving on a Zone Route with a Path Prefix |
| 159 | * Cloudflare matches static assets against the full request pathname, |
| 160 | * so a site attached to a route like `example.com/docs*` only serves |
| 161 | * assets whose uploaded paths carry the `/docs` prefix. Set Vite's |
| 162 | * `base` in your `vite.config.ts` — the emitted HTML references its |
| 163 | * assets under the prefix, and Alchemy keys the uploaded asset manifest |
| 164 | * with the same resolved `base` so the two always agree. |
| 165 | * |
| 166 | * **Example:** vite.config.ts |
| 167 | * ```typescript |
| 168 | * import { defineConfig } from "vite"; |
| 169 | * |
| 170 | * export default defineConfig({ |
| 171 | * base: "/docs/", |
| 172 | * }); |
| 173 | * ``` |
| 174 | * |
| 175 | * **Example:** alchemy.run.ts |
| 176 | * ```typescript |
| 177 | * const docs = yield* Cloudflare.Website.Vite("Docs", { |
| 178 | * routes: [{ pattern: "example.com/docs*", zoneName: "example.com" }], |
| 179 | * }); |
| 180 | * ``` |
| 181 | * |
| 182 | * ### Proxying to a Local Backend in Dev |
| 183 | * Under `alchemy dev`, Vite's `server.proxy` runs in front of the Worker. |
| 184 | * Paths it matches go to its target, WebSockets included with |
| 185 | * `ws: true`, and every other path goes to the Worker. HTTP paths in |
| 186 | * `assets.runWorkerFirst` reach the Worker before the proxy, as they do |
| 187 | * with `@cloudflare/vite-plugin`. `server.proxy` only applies in dev; the |
| 188 | * deployed Worker serves every path. |
| 189 | * |
| 190 | * **Example:** vite.config.ts |
| 191 | * ```typescript |
| 192 | * import { defineConfig } from "vite"; |
| 193 | * |
| 194 | * export default defineConfig({ |
| 195 | * server: { |
| 196 | * proxy: { |
| 197 | * "/api": "http://localhost:3000", |
| 198 | * "/socket": { target: "http://localhost:3000", ws: true }, |
| 199 | * }, |
| 200 | * }, |
| 201 | * }); |
| 202 | * ``` |
| 203 | * |
| 204 | * ### Custom Rebuild Scope |
| 205 | * By default, every non-gitignored file is hashed to decide whether |
| 206 | * a rebuild is needed. Use `memo` to narrow the scope when your |
| 207 | * project has large directories that don't affect the build output. |
| 208 | * |
| 209 | * **Example:** Narrowing the memo scope |
| 210 | * ```typescript |
| 211 | * const site = yield* Cloudflare.Website.Vite("Docs", { |
| 212 | * memo: { |
| 213 | * include: ["src/**", "content/**", "package.json"], |
| 214 | * }, |
| 215 | * }); |
| 216 | * ``` |
| 217 | * |
| 218 | * **Example:** Rebuilding when a sibling workspace package changes |
| 219 | * The default scope only hashes files under the project root (plus the |
| 220 | * nearest lockfile), so edits to a sibling workspace package the app |
| 221 | * imports do not retrigger the build on their own. Add the sibling's |
| 222 | * sources with a `../` include glob — and keep `lockfile: true`, since |
| 223 | * providing `include` otherwise drops the lockfile from the hash: |
| 224 | * ```typescript |
| 225 | * const site = yield* Cloudflare.Website.Vite("Web", { |
| 226 | * rootDir: "apps/web", |
| 227 | * memo: { |
| 228 | * include: ["**\/*", "../../packages/env/src/**"], |
| 229 | * lockfile: true, |
| 230 | * }, |
| 231 | * }); |
| 232 | * ``` |
| 233 | * |
| 234 | * ### Class Form |
| 235 | * Calling `Vite` with no arguments returns a constructor you can |
| 236 | * `extend` to declare the Worker as a named class. The class is both |
| 237 | * an `Effect` you can `yield*` to deploy and a type you can reference |
| 238 | * elsewhere — useful when other resources need to bind to this Worker. |
| 239 | * |
| 240 | * **Example:** Declaring a Worker class |
| 241 | * ```typescript |
| 242 | * class Website extends Cloudflare.Website.Vite<Website>()("Website") {} |
| 243 | * |
| 244 | * const site = yield* Website; |
| 245 | * ``` |
| 246 | * |
| 247 | * @resource |
| 248 | * @product Website |
| 249 | * @category Workers & Compute |
| 250 | */ |
| 251 | export const Vite: { |
| 252 | <Self>(): { |
| 253 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 254 | id: string, |
| 255 | propsEff?: |
| 256 | | InputProps<ViteProps<Bindings>> |
| 257 | | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>, |
| 258 | ): Effect.Effect<Self, never, Req | Providers> & { |
| 259 | new (): Worker<{ |
| 260 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 261 | Bindings, |
| 262 | WorkerAssetsConfig |
| 263 | >[binding]; |
| 264 | }>; |
| 265 | }; |
| 266 | }; |
| 267 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 268 | id: string, |
| 269 | propsEff?: |
| 270 | | InputProps<ViteProps<Bindings>> |
| 271 | | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>, |
| 272 | ): Effect.Effect< |
| 273 | Worker<{ |
| 274 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 275 | Bindings, |
| 276 | WorkerAssetsConfig |
| 277 | >[binding]; |
| 278 | }>, |
| 279 | never, |
| 280 | Req | Providers |
| 281 | >; |
| 282 | } = (<const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 283 | id?: string, |
| 284 | propsEff?: |
| 285 | | InputProps<ViteProps<Bindings>> |
| 286 | | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>, |
| 287 | ) => |
| 288 | id === undefined |
| 289 | ? <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 290 | id: string, |
| 291 | propsEff?: |
| 292 | | InputProps<ViteProps<Bindings>> |
| 293 | | Effect.Effect<InputProps<ViteProps<Bindings>>, never, Req>, |
| 294 | ) => effectClass(Vite(id, propsEff)) |
| 295 | : Worker( |
| 296 | id, |
| 297 | Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => ({ |
| 298 | ...props, |
| 299 | main: undefined!, |
| 300 | vite: { |
| 301 | main: props?.main, |
| 302 | rootDir: props?.rootDir, |
| 303 | memo: props?.memo, |
| 304 | viteEnvironments: props?.viteEnvironments, |
| 305 | }, |
| 306 | })), |
| 307 | )) as any; |