import type { MemoOptions } from "alchemy/Command/Memo";
import type { InputProps } from "alchemy/Input";
import { effectClass } from "alchemy/Util/effect";
import * as Effect from "effect/Effect";
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";
/**
* The specifier of the Octane source-provider module. The package must be
* installed in the user's project — `loadSource` fails with a
* `SourceProviderError` naming it otherwise.
*/
const OCTANE_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/octane/source";
export interface OctaneProps<Bindings extends WorkerBindingProps = {}> extends Omit<
WorkerProps<Bindings>,
"vite" | "main" | "assets" | "source" | "script" | "bundle" | "rules"
> {
/**
* Octane project root (the directory containing `vite.config.ts` and
* `octane.config.ts`). Relative paths resolve from the process working
* directory.
* @default process.cwd()
*/
rootDir?: string;
/**
* Controls which files are content-hashed to decide whether a rebuild is
* needed. By default every non-gitignored file under `rootDir` (plus the
* nearest package-manager lockfile) is hashed; narrow the scope with
* `include`/`exclude` globs when the project sits in a large repository.
*/
memo?: MemoOptions;
/**
* Optional configuration for static asset routing behavior.
* Supports `runWorkerFirst`, `htmlHandling`, `notFoundHandling`, etc.
*
* Octane's intended routing is asset-first with SSR on miss: exact files
* in `dist/client` serve without invoking the Worker, and every miss
* reaches Octane SSR. Leave `notFoundHandling` unset (`"none"`) — both
* `"single-page-application"` and `"404-page"` would prevent
* browser-navigation misses from reaching SSR.
*/
assets?: AssetsConfig;
}
/**
* A Cloudflare Worker deployed from an [OctaneJS](https://octanejs.dev)
* fullstack project.
*
* Alchemy preserves Octane's native compiler and client build, builds the
* server for Workers, and generates the Worker entry. By default,
* `dist/server/worker.js` deploys as the Worker script and `dist/client`
* deploys as static assets; custom Octane `build.outDir` values are also
* supported. No hosting adapter, Wrangler configuration, or separate build
* command is required.
*
* Requires `@alchemy.run/frontend-frameworks` alongside `octane` and
* `@octanejs/vite-plugin` in your project. Keep the native `octane()` plugin,
* Tailwind, and other Vite plugins in `vite.config.ts`, and application
* routes and callbacks in `octane.config.ts`. These files load without
* being rewritten. Existing `adapter: cloudflare()` declarations from
* `@octanejs/adapter-cloudflare` remain supported but are optional; adapters
* for other hosting targets are rejected.
*
* Input files are content-hashed (respecting `.gitignore` by default) so
* unchanged projects skip the build and deploy entirely.
*
* Octane's server runtime needs synchronous SHA-256 and
* `AsyncLocalStorage`, so the `nodejs_compat` compatibility flag (enabled
* by default for every Worker) is required.
*
* A client-only Octane SPA (no `octane.config.ts` routes) is a plain Vite
* project — deploy it with {@link Vite | Cloudflare.Website.Vite} instead,
* where the `octane()` compiler plugin composes with the injected
* Cloudflare Vite plugin.
*
*
* ### Deploying an Octane App
* A single call builds and deploys the app — server-rendered routes,
* server (API) routes, and client assets included. Define the app's routes
* in `octane.config.ts`; `Cloudflare.Website.Octane` selects the Worker build:
*
* **Example:** octane.config.ts
* ```typescript
* import { defineConfig, RenderRoute } from "@octanejs/vite-plugin";
*
* export default defineConfig({
* router: {
* routes: [new RenderRoute({ path: "/", entry: ["App", "/src/App.tsx"] })],
* },
* });
* ```
*
* **Example:** alchemy.run.ts
* ```typescript
* const site = yield* Cloudflare.Website.Octane("Website");
* ```
*
* **Example:** Octane project in a subdirectory
* ```typescript
* const site = yield* Cloudflare.Website.Octane("Website", {
* rootDir: "apps/web",
* });
* ```
*
* ### Bindings
* Values passed via `env` reach Octane middleware and `ServerRoute`
* handlers through `context.platform`. The generated Worker entry supplies
* the Cloudflare `{ env, ctx }` pair, so `platform.env.MY_KV` is the live
* binding and `platform.ctx.waitUntil` schedules background work.
*
* **Example:** Reading a binding from a ServerRoute
* ```typescript
* // octane.config.ts route
* // new ServerRoute({
* // path: "/api/hello",
* // methods: ["GET"],
* // handler: (context) => {
* // const platform = context.platform as { env: { API_KEY: string } };
* // return Response.json({ hasKey: platform.env.API_KEY !== undefined });
* // },
* // })
*
* const site = yield* Cloudflare.Website.Octane("Website", {
* env: {
* API_KEY: Config.Redacted("API_KEY"),
* },
* });
* ```
*
* **Example:** Binding a KV namespace
* ```typescript
* const cache = yield* Cloudflare.KV.Namespace("Cache");
*
* const site = yield* Cloudflare.Website.Octane("Website", {
* env: {
* CACHE: cache,
* },
* });
* ```
*
* ### Dev
* `alchemy dev` runs Octane's own Vite dev server (the plugin's in-process
* SSR middleware — rendering, server routes, and RPC with full HMR).
* NOTE: Octane's dev middleware does not supply request-scoped platform
* bindings (`context.platform` is `undefined` in dev — an upstream
* limitation), so code touching `platform.env` must tolerate `undefined`
* during dev; bindings are live in deployed Workers.
*
* ### Custom Rebuild Scope
* By default, every non-gitignored file is hashed to decide whether a
* rebuild is needed. Use `memo` to narrow the scope when the project
* lives in a large repository.
*
* **Example:** Narrowing the memo scope
* ```typescript
* const site = yield* Cloudflare.Website.Octane("Website", {
* memo: {
* include: ["src/**", "public/**", "octane.config.ts", "vite.config.ts", "package.json"],
* },
* });
* ```
*
* ### Class Form
* Calling `Octane` 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.Website.Octane<Website>()(
* "Website",
* ) {}
*
* const site = yield* Website;
* ```
*
* @resource
* @product Website
* @category Workers & Compute
*/
export const Octane: {
<Self>(): {
<const Bindings extends WorkerBindingProps = {}, Req = never>(
id: string,
propsEff?:
| InputProps<OctaneProps<Bindings>>
| Effect.Effect<InputProps<OctaneProps<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<OctaneProps<Bindings>>
| Effect.Effect<InputProps<OctaneProps<Bindings>>, never, Req>,
): Effect.Effect<
Worker<{
[binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings<
Bindings,
WorkerAssetsConfig
>[binding];
}>,
never,
Req | Providers
>;
} = (<const Bindings extends WorkerBindingProps = {}, Req = never>(
id?: string,
propsEff?:
| InputProps<OctaneProps<Bindings>>
| Effect.Effect<InputProps<OctaneProps<Bindings>>, never, Req>,
) =>
id === undefined
? <const Bindings extends WorkerBindingProps = {}, Req = never>(
id: string,
propsEff?:
| InputProps<OctaneProps<Bindings>>
| Effect.Effect<InputProps<OctaneProps<Bindings>>, never, Req>,
) => effectClass(Octane(id, propsEff))
: Worker(
id,
Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => ({
...props,
// Octane's server bundle externalizes `node:` modules for
// workerd's native node-compat — `getCompatibility` already
// adds `nodejs_compat` to every non-python Worker.
main: undefined!,
source: {
provider: OCTANE_SOURCE_PROVIDER,
devMode: "server",
rootDir: props?.rootDir,
options: {
rootDir: props?.rootDir,
memo: props?.memo,
},
},
})),
)) as any;