1import * as Namespace from "../../Namespace.ts";
2import { makeFrameworkSite, type FrameworkSiteProps } from "./FrameworkSite.ts";
3
4/** The framework-integration package that drives the Vocs build. */
5export const VOCS_FRAMEWORK_SPECIFIER =
6 "@alchemy.run/frontend-frameworks/vocs/node";
7
8/** The Node container deploy target for the Vocs build. */
9export const VOCS_NODE_TARGET_SPECIFIER =
10 "@alchemy.run/frontend-frameworks/vocs/node";
11
12export interface VocsProps extends FrameworkSiteProps {
13 /**
14 * Vocs build output directory, relative to {@link rootDir}. Set this when
15 * `vocs.config.*` customizes `outDir` so generated output stays outside the
16 * rebuild hash.
17 * @default "dist"
18 */
19 outDir?: string;
20}
21
22/**
23 * Deploy a [Vocs](https://vocs.dev) documentation project to Railway: static
24 * assets first, then Vocs' Waku RSC handler (`/about` not `/about/`) from
25 * one `Railway.Service`.
26 *
27 * Requires `@alchemy.run/frontend-frameworks`, `vocs`, and Vocs' Waku peer
28 * dependencies in the project.
29 *
30 * During `alchemy dev` the site is Vocs' own dev server and no cloud
31 * resources are created. `Alchemy.remote()` opts back into the live
32 * Service path.
33 *
34 * ### Deploying a Vocs Site
35 * **Example:** Vocs documentation site
36 * ```typescript
37 * const docs = yield* Railway.Website.Vocs("Docs", {
38 * rootDir: "./docs",
39 * });
40 * ```
41 *
42 * ### Custom Build Output
43 * **Example:** Custom output directory
44 * ```typescript
45 * // vocs.config.ts: defineConfig({ outDir: "build" })
46 * const docs = yield* Railway.Website.Vocs("Docs", {
47 * rootDir: "./docs",
48 * outDir: "build",
49 * });
50 * ```
51 *
52 * @resource
53 * @product Website
54 */
55export const Vocs = (id: string, props: VocsProps = {}) =>
56 makeFrameworkSite(id, props, {
57 name: "Vocs",
58 framework: VOCS_FRAMEWORK_SPECIFIER,
59 target: VOCS_NODE_TARGET_SPECIFIER,
60 options: props.outDir !== undefined ? { outDir: props.outDir } : undefined,
61 }).pipe(Namespace.push(id));