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