@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 214 lines 6.45 KB
Raw
1 ---
2 title: Foldkit
3 description: Deploy Foldkit SPA, SSR, SSG, and hybrid applications to Prisma Compute with native local development.
4 sidebar:
5 order: 8
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks @vercel/nft";
11
12 `Prisma.Website.Foldkit` deploys a [Foldkit](https://foldkit.dev) app to
13 Prisma Compute. It supports browser-only SPAs, server-side rendering (SSR), static site
14 generation (SSG), and hybrid rendering. Foldkit's Vite plugin generates the
15 handler and assets; Alchemy packages them for deployment.
16
17 ## Install
18
19 Install the build-time integration; the resource loads `/foldkit` and
20 `/foldkit/neon` from your frontend project:
21
22 <PackageManagers dev={devDeps} />
23
24 ## Configure Vite
25
26 Keep Foldkit's Vite setup and your existing plugins:
27
28 ```typescript
29 // vite.config.ts
30 import { foldkit } from "@foldkit/vite-plugin";
31 import tailwindcss from "@tailwindcss/vite";
32 import { defineConfig } from "vite";
33
34 export default defineConfig({
35 plugins: [foldkit(), tailwindcss()],
36 optimizeDeps: { entries: ["src/entry.ts"] },
37 });
38 ```
39
40 ## Server rendering and prerendering
41
42 Configure rendering in the application's `foldkit(...)` plugin. This example
43 uses Foldkit 0.167.0, `@foldkit/vite-plugin` 0.27.0 and compatible Effect
44 dependencies:
45
46 ```typescript
47 // vite.config.ts
48 import { foldkit } from "@foldkit/vite-plugin";
49 import { defineConfig } from "vite";
50
51 export default defineConfig({
52 plugins: [
53 foldkit({
54 ssr: {
55 serverEntry: "/src/entry.server.ts",
56 clientEntry: "/src/entry.ts",
57 build: true,
58 },
59 }),
60 ],
61 });
62 ```
63
64 The server entry exports `renderPage` and `renderDocument`. Import stylesheets
65 from the client entry and use `Runtime.hydrate` to start the browser application.
66 Remove the source `index.html` for this build: Foldkit generates the complete
67 HTML document, including the client script, stylesheets and module preload links.
68
69 ```typescript
70 // src/entry.server.ts
71 import { Server } from "foldkit/experimental";
72
73 export const renderDocument = Server.renderDocument;
74 ```
75
76 Keep your application's `renderPage` export alongside the document renderer.
77 Foldkit currently exposes its server rendering API through `foldkit/experimental`;
78 see its [server rendering guide](https://foldkit.dev/core/server-rendering) for
79 the application and hydration contract.
80
81 For static site generation (SSG), change `build` to `{ prerender: true }` and
82 export the URLs to generate from the server entry:
83
84 ```typescript
85 // src/entry.server.ts
86 export const prerenderPaths = ["/", "/about"];
87 ```
88
89 SSG renders those URLs during the build. SSR renders a page when its request
90 arrives. A hybrid application prerenders some URLs and renders others on request.
91 The same `renderPage` and `renderDocument` exports serve both delivery policies.
92
93 The same Website declaration deploys the client assets and generated handler.
94 GET and HEAD requests serve matching assets and prerendered pages first;
95 remaining requests go to the handler. Other methods bypass static assets.
96 The application owns its response status and headers through `renderPage`.
97 For an SSG-only application, return 404 for URLs outside its generated route set;
98 allowing those URLs to render on request makes the deployment hybrid.
99
100 Browser-only builds use SPA fallback. Server builds send unmatched requests to
101 the handler. Explicit `assets.notFoundHandling` settings override these defaults.
102
103 Vite's resolved `base` also mounts the client assets. With `base: "/app/"`,
104 `/app/assets/main.js` serves `assets/main.js` from the client output. SPA fallback
105 is limited to that prefix; server handlers receive the original URL.
106
107 ## Declare the Website
108
109 ```typescript
110 // alchemy.run.ts
111 import * as Prisma from "@alchemy.run/prisma";
112
113 export const Website = Prisma.Website.Foldkit("Website", {
114 rootDir: "applications/web",
115 });
116 ```
117
118 Omit `rootDir` for an app at `.`. Omit `project` to create a
119 database-less Prisma project on live deploy, or pass an existing project.
120
121 ## Add it to the Stack
122
123 ```typescript
124 // alchemy.run.ts
125 import * as Alchemy from "alchemy";
126 import * as Effect from "effect/Effect";
127
128 export default Alchemy.Stack(
129 "MyFoldkitSite",
130 { providers: Prisma.providers(), state: Alchemy.localState() },
131 Effect.gen(function* () {
132 const site = yield* Website;
133 return { url: site.url };
134 }),
135 );
136 ```
137
138 `site.url` is the Compute endpoint on deploy and Vite's local URL in dev.
139
140 ## Add environment variables
141
142 ```diff lang="typescript"
143 export const Website = Prisma.Website.Foldkit("Website", {
144 rootDir: "applications/web",
145 + env: {
146 + VITE_API_URL: "https://api.example.com",
147 + },
148 });
149 ```
150
151 `env` is applied before build and dev, and passed to Compute. Server code
152 reads private values from `process.env`. Vite inlines `VITE_*` keys into the
153 browser build; keep secrets out of those keys and serialized Foldkit Flags.
154
155 ## Read the environment in client code
156
157 ```typescript
158 // src/vite-env.d.ts
159 /// <reference types="vite/client" />
160
161 interface ImportMetaEnv {
162 readonly VITE_API_URL: string;
163 }
164 ```
165
166 This declares the client-visible key for TypeScript.
167
168 ```typescript
169 const apiUrl = import.meta.env.VITE_API_URL;
170 ```
171
172 Vite replaces the lookup with the build-time value.
173
174 ## Deep links
175
176 For browser-only builds, `assets.notFoundHandling` defaults to `"single-page-application"`.
177 A path like `/counter/42` returns `index.html` with status 200, letting
178 Foldkit's client router resolve it. For real 404 responses instead:
179
180 ```typescript
181 export const Website = Prisma.Website.Foldkit("Website", {
182 assets: { notFoundHandling: "404-page" },
183 });
184 ```
185
186 ## Local dev
187
188 `bun alchemy dev` runs Vite with Foldkit live reload and devtools. The Website
189 creates no Prisma resources. `.pipe(Alchemy.remote())` selects the live
190 path during dev. Pin the local address when running several apps:
191
192 ```typescript
193 export const Website = Prisma.Website.Foldkit("Website", {
194 dev: { host: "127.0.0.1", port: 5180, strictPort: true },
195 });
196 ```
197
198 ## Custom domain
199
200 ```typescript
201 const site = yield* Prisma.Website.Foldkit("Web", {
202 domain: "app.example.com",
203 });
204 ```
205
206 This creates `Prisma.CustomDomain`. Configure the returned DNS records yourself
207 and verify status before cutover. See
208 [Custom domains](/prisma/frontend/websites#custom-domains).
209
210 ## Where next
211
212 - [Foldkit API](/providers/prisma/website/foldkit).
213 - [Foldkit example](https://github.com/alchemy-run/alchemy/tree/main/examples/prisma-website-foldkit).
214 - [Vite](/prisma/frontend/vite), [Websites](/prisma/frontend/websites), and [Compute apps](/prisma/compute/apps).