@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 175 lines 4.52 KB
Raw
1 ---
2 title: Vocs
3 description: Deploy a Vocs docs site to Railway with Railway.Website.Vocs — prerendered HTML on a Railway Service, extensionless routes, and Vocs' own dev server under alchemy dev.
4 sidebar:
5 order: 10
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Railway.Website.Vocs` deploys a [Vocs](https://vocs.dev)
13 documentation project as one
14 [Railway.Service](/railway/compute/services) from a container
15 image. Vocs prerenders static HTML; a Node static-file server
16 serves extensionless pages (`/about` not `/about/`). Your `vocs.config.*` loads natively — there is
17 no adapter to install.
18
19 ## Install
20
21 The build integration is not bundled with alchemy. Install
22 `@alchemy.run/frontend-frameworks`; the resource loads
23 `/vocs/node` from your project at deploy time. It is only used at
24 build time, so a dev dependency is enough:
25
26 <PackageManagers dev={devDeps} />
27
28 The project also needs `vocs` and Vocs' Waku peer dependencies.
29
30 ## Configure Vocs
31
32 Your `vocs.config.*` file loads natively — title, sidebar, and any
33 other Vocs options work exactly as they do outside Alchemy:
34
35 ```typescript
36 // vocs.config.ts
37 import { defineConfig } from "vocs/config";
38
39 export default defineConfig({
40 title: "Docs",
41 sidebar: [
42 { text: "Home", link: "/" },
43 { text: "Guide", link: "/guide" },
44 ],
45 });
46 ```
47
48 If `vocs.config.*` sets `outDir`, pass the same value on the
49 resource (default `"dist"`) so generated output stays outside the
50 rebuild hash:
51
52 ```typescript
53 export const Website = Railway.Website.Vocs("Website", {
54 rootDir: "./docs",
55 outDir: "build",
56 });
57 ```
58
59 ## Declare the Website
60
61 Declare the site as a module-level const (rather than inline in the
62 Stack):
63
64 ```typescript
65 // alchemy.run.ts
66 import * as Railway from "@alchemy.run/railway";
67
68 export const Website = Railway.Website.Vocs("Website", {
69 rootDir: "./docs",
70 });
71 ```
72
73 Omit `project` to create a `Railway.Project` under this site's
74 namespace. Pass an existing `Railway.Project` when the site should
75 live next to other Services:
76
77 ```typescript
78 export const Site = Railway.Project("Site");
79
80 export const Website = Railway.Website.Vocs("Website", {
81 rootDir: "./docs",
82 project: Site,
83 });
84 ```
85
86 ## Add it to the Stack
87
88 Yield the site from your Stack and return its URL:
89
90 ```typescript
91 // alchemy.run.ts
92 import * as Alchemy from "alchemy";
93 import * as Effect from "effect/Effect";
94
95 export default Alchemy.Stack(
96 "MyVocsSite",
97 {
98 providers: Railway.providers(),
99 state: Alchemy.localState(),
100 },
101 Effect.gen(function* () {
102 const site = yield* Website;
103 return { url: site.url };
104 }),
105 );
106 ```
107
108 The live URL is the generated `https://{name}.up.railway.app`
109 (`site.service.url`). The Service listens on port 3000 with
110 `healthcheck: "/health"`. `site.service` and `site.project` are set
111 on deploy.
112
113 ## Add environment variables
114
115 Top-level `env` is copied onto `process.env` before build and
116 `alchemy dev`, and onto the Service at deploy:
117
118 ```diff lang="typescript"
119 // alchemy.run.ts
120 export const Website = Railway.Website.Vocs("Website", {
121 rootDir: "./docs",
122 + env: {
123 + DOCS_TITLE: "Hello from Alchemy!",
124 + },
125 });
126 ```
127
128 These are process environment variables, not Worker bindings.
129
130 ## Read the environment
131
132 Vocs prerenders at build time, so page content that reads
133 `process.env` is baked into the HTML. The same values are set on
134 the hosted Node process; there is no request-time Vocs server.
135
136 ```typescript
137 const title = process.env.DOCS_TITLE ?? "Docs";
138 ```
139
140 ## Local development
141
142 `alchemy dev` runs Vocs' own dev server (native HMR) instead of
143 deploying; `site.url` is the local address and no Railway resources
144 are created (`service` and `project` are `undefined`). Wrap the
145 site in `Alchemy.remote()` to deploy the live
146 Service even during dev:
147
148 ```typescript
149 export const Website = Railway.Website.Vocs("Website", {
150 rootDir: "./docs",
151 }).pipe(Alchemy.remote());
152 ```
153
154 ## Custom domain
155
156 `domain` is a hostname string. Alchemy attaches a
157 [`CustomDomain`](/railway/networking) (`targetPort: 3000`); `url`
158 becomes `https://{domain}` instead of `*.up.railway.app`:
159
160 ```typescript
161 export const Website = Railway.Website.Vocs("Website", {
162 rootDir: "./docs",
163 domain: "docs.example.com",
164 });
165 ```
166
167 ## Where next
168
169 - [`Vocs` reference](/providers/railway/website/vocs) — every prop
170 and attribute
171 - [Projects](/railway/compute/projects) and
172 [Services](/railway/compute/services) — the container the site
173 runs in
174 - [Custom domains](/railway/networking) — hostnames on a Service
175 - [Railway](/railway) — the Railway provider hub