The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { MemoOptions } from "alchemy/Command/Memo"; |
| 2 | import type { InputProps } from "alchemy/Input"; |
| 3 | import { effectClass } from "alchemy/Util/effect"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import type { Providers } from "../Providers.ts"; |
| 6 | import type { AssetsConfig } from "../Workers/Assets.ts"; |
| 7 | import { |
| 8 | Worker, |
| 9 | type NormalizedBindings, |
| 10 | type WorkerAssetsConfig, |
| 11 | type WorkerBindingProps, |
| 12 | type WorkerProps, |
| 13 | } from "../Workers/Worker.ts"; |
| 14 | |
| 15 | const VOCS_SOURCE_PROVIDER = "@alchemy.run/frontend-frameworks/vocs/source"; |
| 16 | |
| 17 | export interface VocsProps<Bindings extends WorkerBindingProps = {}> extends Omit< |
| 18 | WorkerProps<Bindings>, |
| 19 | "vite" | "main" | "assets" | "source" | "script" | "bundle" | "rules" |
| 20 | > { |
| 21 | /** |
| 22 | * Root directory of the Vocs project. |
| 23 | * @default process.cwd() |
| 24 | */ |
| 25 | rootDir?: string; |
| 26 | /** |
| 27 | * Vocs build output directory, relative to {@link rootDir}. Set this when |
| 28 | * `vocs.config.*` customizes `outDir` so generated output stays outside the |
| 29 | * rebuild hash. |
| 30 | * @default "dist" |
| 31 | */ |
| 32 | outDir?: string; |
| 33 | /** |
| 34 | * Controls which files feed the content hash that decides whether Vocs |
| 35 | * rebuilds. By default every non-gitignored file under {@link rootDir} is |
| 36 | * hashed, plus the nearest package-manager lockfile. |
| 37 | */ |
| 38 | memo?: MemoOptions; |
| 39 | /** |
| 40 | * Static asset routing configuration. Vocs links prerendered pages without |
| 41 | * trailing slashes, so extensionless routing is enabled by default. |
| 42 | * @default { htmlHandling: "drop-trailing-slash" } |
| 43 | */ |
| 44 | assets?: AssetsConfig; |
| 45 | } |
| 46 | |
| 47 | // These options are inspected while constructing the Worker. Resolve them in |
| 48 | // the outer props Effect; pass-through properties can remain deferred Inputs. |
| 49 | type VocsInput<Bindings extends WorkerBindingProps> = InputProps<VocsProps<Bindings>, "assets">; |
| 50 | |
| 51 | /** |
| 52 | * A Cloudflare Worker deployed from a [Vocs](https://vocs.dev) documentation project. |
| 53 | * |
| 54 | * Vocs' `vocs.config.*` loads natively. Alchemy runs Vocs' Waku/RSC build, |
| 55 | * deploys its server environments as a Worker, and publishes the client and |
| 56 | * prerendered output as static assets. No Vite or Wrangler config is required. |
| 57 | * |
| 58 | * Requires `@alchemy.run/frontend-frameworks`, `vocs`, and Vocs' Waku peer |
| 59 | * dependencies in the project. |
| 60 | * |
| 61 | * Input files are content-hashed (respecting `.gitignore` by default), so an |
| 62 | * unchanged project skips its build and deployment. Vocs' server runtime uses |
| 63 | * Node APIs, enabled by the Worker's compatibility date |
| 64 | * flags automatically. |
| 65 | * |
| 66 | * ### Deploying a Vocs Site |
| 67 | * A single resource builds the documentation project and deploys its server |
| 68 | * runtime, prerendered pages, generated files, and public assets. |
| 69 | * |
| 70 | * **Example:** Vocs documentation site |
| 71 | * ```typescript |
| 72 | * const docs = yield* Cloudflare.Website.Vocs("Docs", { |
| 73 | * rootDir: "./docs", |
| 74 | * }); |
| 75 | * ``` |
| 76 | * |
| 77 | * ### Bindings |
| 78 | * Pass Cloudflare resources through `env` like any other Worker. Server-side |
| 79 | * Vocs and MDX code can access them from `cloudflare:workers`. |
| 80 | * |
| 81 | * **Example:** Vocs with a KV namespace |
| 82 | * ```typescript |
| 83 | * const searchCache = yield* Cloudflare.KV.Namespace("SearchCache"); |
| 84 | * |
| 85 | * const docs = yield* Cloudflare.Website.Vocs("Docs", { |
| 86 | * rootDir: "./docs", |
| 87 | * env: { |
| 88 | * SEARCH_CACHE: searchCache, |
| 89 | * }, |
| 90 | * }); |
| 91 | * ``` |
| 92 | * |
| 93 | * ### Custom Build Output |
| 94 | * Vocs configuration continues to own the output directory. When |
| 95 | * `vocs.config.*` changes `outDir`, mirror that value on the resource so the |
| 96 | * generated directory is excluded from the rebuild hash and read correctly. |
| 97 | * |
| 98 | * **Example:** Custom output directory |
| 99 | * ```typescript |
| 100 | * // vocs.config.ts: defineConfig({ outDir: "build" }) |
| 101 | * const docs = yield* Cloudflare.Website.Vocs("Docs", { |
| 102 | * rootDir: "./docs", |
| 103 | * outDir: "build", |
| 104 | * }); |
| 105 | * ``` |
| 106 | * |
| 107 | * ### Custom Rebuild Scope |
| 108 | * Use `memo` to narrow the files that trigger a rebuild in large projects. |
| 109 | * |
| 110 | * **Example:** Narrowing the memo scope |
| 111 | * ```typescript |
| 112 | * const docs = yield* Cloudflare.Website.Vocs("Docs", { |
| 113 | * rootDir: "./docs", |
| 114 | * memo: { |
| 115 | * include: ["src/**", "public/**", "vocs.config.ts", "package.json"], |
| 116 | * }, |
| 117 | * }); |
| 118 | * ``` |
| 119 | * |
| 120 | * ### Class Form |
| 121 | * Calling `Vocs` without arguments returns a constructor for declaring the |
| 122 | * deployed Worker as a named class. |
| 123 | * |
| 124 | * **Example:** Declaring a Vocs Worker class |
| 125 | * ```typescript |
| 126 | * class Docs extends Cloudflare.Website.Vocs<Docs>()("Docs", { |
| 127 | * rootDir: "./docs", |
| 128 | * }) {} |
| 129 | * |
| 130 | * const docs = yield* Docs; |
| 131 | * ``` |
| 132 | * |
| 133 | * @resource |
| 134 | * @product Website |
| 135 | * @category Workers & Compute |
| 136 | */ |
| 137 | export const Vocs: { |
| 138 | <Self>(): { |
| 139 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 140 | id: string, |
| 141 | propsEff?: VocsInput<Bindings> | Effect.Effect<VocsInput<Bindings>, never, Req>, |
| 142 | ): Effect.Effect<Self, never, Req | Providers> & { |
| 143 | new (): Worker<{ |
| 144 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 145 | Bindings, |
| 146 | WorkerAssetsConfig |
| 147 | >[binding]; |
| 148 | }>; |
| 149 | }; |
| 150 | }; |
| 151 | <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 152 | id: string, |
| 153 | propsEff?: VocsInput<Bindings> | Effect.Effect<VocsInput<Bindings>, never, Req>, |
| 154 | ): Effect.Effect< |
| 155 | Worker<{ |
| 156 | [binding in keyof NormalizedBindings<Bindings, WorkerAssetsConfig>]: NormalizedBindings< |
| 157 | Bindings, |
| 158 | WorkerAssetsConfig |
| 159 | >[binding]; |
| 160 | }>, |
| 161 | never, |
| 162 | Req | Providers |
| 163 | >; |
| 164 | } = (<const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 165 | id?: string, |
| 166 | propsEff?: VocsInput<Bindings> | Effect.Effect<VocsInput<Bindings>, never, Req>, |
| 167 | ) => |
| 168 | id === undefined |
| 169 | ? <const Bindings extends WorkerBindingProps = {}, Req = never>( |
| 170 | id: string, |
| 171 | propsEff?: VocsInput<Bindings> | Effect.Effect<VocsInput<Bindings>, never, Req>, |
| 172 | ) => effectClass(Vocs(id, propsEff)) |
| 173 | : Worker( |
| 174 | id, |
| 175 | Effect.map(Effect.isEffect(propsEff) ? propsEff : Effect.succeed(propsEff), (props) => ({ |
| 176 | ...props, |
| 177 | // The Worker compatibility resolver enables Node.js APIs from |
| 178 | // the date (or adds the flag when a caller pins an older date). |
| 179 | assets: { |
| 180 | htmlHandling: "drop-trailing-slash" as const, |
| 181 | ...props?.assets, |
| 182 | }, |
| 183 | main: undefined!, |
| 184 | source: { |
| 185 | provider: VOCS_SOURCE_PROVIDER, |
| 186 | devMode: "server", |
| 187 | options: { |
| 188 | rootDir: props?.rootDir, |
| 189 | outDir: props?.outDir, |
| 190 | memo: props?.memo, |
| 191 | }, |
| 192 | }, |
| 193 | })), |
| 194 | )) as any; |