clover's git

the-knife

1	---
2	title: Vocs
3	description: Deploy Vocs documentation to Prisma Compute with Prisma.Website.Vocs — static assets and Waku RSC on Bun, with Vocs dev locally.
4	sidebar:
5	order: 10
6	---
7
8	import { Code, Tabs, TabItem } from "@astrojs/starlight/components";
9
10	export const devDeps = "@alchemy.run/frontend-frameworks @vercel/nft";
11
12	`Prisma.Website.Vocs` builds a [Vocs](https://vocs.dev) documentation
13	site and runs it on **Bun in Prisma Compute**. The shared Node target
14	serves client files and prerendered HTML first, then falls through to
15	Vocs' Waku RSC handler. The result is uploaded as `tar.gz`, not a Docker
16	image. Extensionless pages such as `/about` retain their normal URLs.
17
18	## Install
19
20	Install the build-time integration; the resource loads `/vocs/node`
21	from your project. Keep `vocs` and its Waku peer dependencies installed.
22
23	<Tabs syncKey="pkgManager">
24	<TabItem label="bun" icon="bun"><Code code={`bun add -d ${devDeps}`} lang="sh" /></TabItem>
25	<TabItem label="npm" icon="npm"><Code code={`npm install -D ${devDeps}`} lang="sh" /></TabItem>
26	<TabItem label="pnpm" icon="pnpm"><Code code={`pnpm add -D ${devDeps}`} lang="sh" /></TabItem>
27	<TabItem label="yarn" icon="seti:yarn"><Code code={`yarn add -D ${devDeps}`} lang="sh" /></TabItem>
28	</Tabs>
29
30	## Configure Vocs
31
32	Your `vocs.config.*` loads natively. No adapter is needed:
33
34	```typescript
35	// vocs.config.ts
36	import { defineConfig } from "vocs/config";
37
38	export default defineConfig({
39	title: "Docs",
40	sidebar: [
41	{ text: "Home", link: "/" },
42	{ text: "Guide", link: "/guide" },
43	],
44	});
45	```
46
47	Vocs controls its output directory through `vocs.config.*`; the default is
48	`dist`. If you change it to `build`, also ignore that directory so generated
49	files stay out of the default build-input hash:
50
51	```text
52	# .gitignore
53	build/
54	```
55
56	## Declare the Website
57
58	```typescript
59	// alchemy.run.ts
60	import * as Prisma from "alchemy/Prisma";
61
62	export const Website = Prisma.Website.Vocs("Website", {
63	rootDir: "./docs",
64	});
65	```
66
67	Omit `rootDir` for a project at `.`. Omit `project` for a database-less
68	Prisma project created on live deploy, or pass an existing project.
69
70	## Add it to the Stack
71
72	```typescript
73	// alchemy.run.ts
74	import * as Alchemy from "alchemy";
75	import * as Effect from "effect/Effect";
76
77	export default Alchemy.Stack(
78	"MyVocsSite",
79	{ providers: Prisma.providers(), state: Alchemy.localState() },
80	Effect.gen(function* () {
81	const site = yield* Website;
82	return { url: site.url };
83	}),
84	);
85	```
86
87	`site.url` is the Compute endpoint on deploy and the local Vocs URL in dev.
88
89	## Add environment variables
90
91	```diff lang="typescript"
92	export const Website = Prisma.Website.Vocs("Website", {
93	rootDir: "./docs",
94	+ env: { DOCS_TITLE: "Hello from Alchemy!" },
95	});
96	```
97
98	`env` is applied before build and dev, and passed to Compute. These are
99	process environment variables, not Worker bindings.
100
101	## Read the environment
102
103	```typescript
104	const title = process.env.DOCS_TITLE ?? "Docs";
105	```
106
107	Prerendered pages capture these values at build time; dynamic pages
108	read the runtime environment. Vocs defaults to dynamic rendering, so
109	its Waku RSC handler stays in the artifact. Deploying only a static
110	HTML shell would drop that handler and leave dynamic pages empty.
111
112	## Local development
113
114	`bun alchemy dev` runs Vocs' own dev server with HMR and creates no
115	Prisma resources for the Website. Opt into live deployment during dev:
116
117	```typescript
118	export const Website = Prisma.Website.Vocs("Website", {
119	rootDir: "./docs",
120	}).pipe(Alchemy.remote());
121	```
122
123	## Custom domain
124
125	```typescript
126	export const Website = Prisma.Website.Vocs("Website", {
127	rootDir: "./docs",
128	domain: "docs.example.com",
129	});
130	```
131
132	`domain` creates `Prisma.CustomDomain` and changes `site.url` to the
133	HTTPS hostname. The app must be on the project's current default branch.
134	Configure returned DNS records yourself and verify status before cutover;
135	see [Custom domains](/prisma/frontend/websites#custom-domains).
136
137	## Where next
138
139	- [Vocs API](/providers/prisma/website/vocs).
140	- [Vocs example](https://github.com/alchemy-run/alchemy/tree/main/examples/prisma-website-vocs).
141	- [Websites](/prisma/frontend/websites) and [Compute apps](/prisma/compute/apps).