@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, 04:45 UTC

main
mdx 233 lines 6.89 KB
Raw
1 ---
2 title: SolidStart
3 description: Deploy a SolidStart app to Fly with Fly.Website.SolidStart — nitro's node preset on a Machine, prerendered pages baked into the image, and SolidStart's own Vite dev server under alchemy dev.
4 sidebar:
5 order: 10.5
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Fly.Website.SolidStart` deploys a
13 [SolidStart](https://start.solidjs.com) app to Fly. It runs your
14 project's own `vite build` and appends nitro's `node` preset: the SSR
15 server runs as a Node [`Fly.Service`](/fly/compute/services) on a
16 Machine, and client assets plus prerendered pages are baked into the
17 image and served first. Omit `app` and Alchemy creates a
18 [`Fly.App`](/fly/compute/apps) plus a shared IPv4 so
19 `https://{app}.fly.dev` answers. No adapter, no `fly.toml`.
20
21 :::note[Verified version line]
22 This page tracks `@solidjs/start` **2.x** with
23 `@solidjs/vite-plugin-nitro-2` — the Vite-native line where
24 `solidStart()` is a plain Vite plugin and nitro is a second plugin.
25 :::
26
27 ## Install
28
29 The build integration is not bundled with alchemy. Install
30 `@alchemy.run/frontend-frameworks`; the resource loads its
31 `/solidstart` and `/solidstart/node` exports from your project at
32 deploy time. It is only used at build time, so a dev dependency is
33 enough:
34
35 <PackageManagers dev={devDeps} />
36
37 `@solidjs/vite-plugin-nitro-2` is the server half of a SolidStart
38 build and must be a project dependency too:
39
40 <PackageManagers add="@solidjs/vite-plugin-nitro-2" />
41
42 ## Configure Vite
43
44 Your `vite.config.ts` is the SolidStart plugin — no adapter, no
45 nitro wiring. Vite plugins like Tailwind go in `plugins` as usual:
46
47 ```typescript
48 // vite.config.ts
49 import { solidStart } from "@solidjs/start/config";
50 import tailwindcss from "@tailwindcss/vite";
51 import { defineConfig } from "vite";
52
53 export default defineConfig({
54 plugins: [solidStart(), tailwindcss()],
55 });
56 ```
57
58 Alchemy appends its own `nitroV2Plugin()` instance at build time,
59 carrying nitro's `node` preset. Don't register `nitroV2Plugin()`
60 yourself — the appended instance would discard its options, so the
61 build fails with an actionable error instead. Pass nitro options
62 through the resource's `nitro` prop; see [Prerendering](#prerendering)
63 below.
64
65 ## Declare the Website
66
67 Declare the site as a module-level const (rather than inline in the
68 Stack):
69
70 ```typescript
71 // alchemy.run.ts
72 import * as Fly from "@alchemy.run/fly";
73
74 export const Website = Fly.Website.SolidStart("Website");
75 ```
76
77 Pass `app` to put the site on an existing `Fly.App`. `rootDir` is the
78 project root — the directory holding `package.json` and `vite.config.*`.
79 It defaults to `"."`, so set it only when the app does not sit next to
80 `alchemy.run.ts`:
81
82 ```typescript
83 export const Website = Fly.Website.SolidStart("Website", {
84 rootDir: "./app",
85 });
86 ```
87
88 ## Add it to the Stack
89
90 Yield the site from your Stack and return its URL:
91
92 ```typescript
93 // alchemy.run.ts
94 import * as Alchemy from "alchemy";
95 import * as Effect from "effect/Effect";
96
97 export default Alchemy.Stack(
98 "MySolidStartSite",
99 {
100 providers: Fly.providers(),
101 state: Alchemy.localState(),
102 },
103 Effect.gen(function* () {
104 const site = yield* Website;
105 return { url: site.url };
106 }),
107 );
108 ```
109
110 The live `url` is `https://{app}.fly.dev`. `site.app`,
111 `site.service`, `site.ip`, and `site.certificate` are the Fly
112 resources underneath — `undefined` during `alchemy dev`.
113
114 See the [SolidStart API reference](/providers/fly/website/solidstart)
115 for every prop and attribute.
116
117 ## Add environment variables
118
119 Process environment is a top-level `env` map — plain strings, or
120 `Redacted` values:
121
122 ```diff lang="typescript"
123 // alchemy.run.ts
124 export const Website = Fly.Website.SolidStart("Website", {
125 + env: {
126 + API_BASE: "https://api.example.com",
127 + },
128 });
129 ```
130
131 The values are copied onto `process.env` before the build and the
132 dev server, and onto the Machine at deploy time, so server code
133 reads the same keys in both modes. Client inlining is whatever Vite
134 does (`VITE_` prefixes).
135
136 An output from another resource only exists once that resource is
137 yielded, so declare the site inside the Stack generator instead:
138
139 ```typescript
140 // alchemy.run.ts
141 Effect.gen(function* () {
142 const api = yield* Api;
143
144 const site = yield* Fly.Website.SolidStart("Website", {
145 env: { API_BASE: api.url },
146 });
147
148 return { url: site.url };
149 });
150 ```
151
152 ## Read the environment in server code
153
154 The SolidStart server is a plain Node process, so API routes,
155 server functions, and SSR read the environment from `process.env`:
156
157 ```typescript
158 // src/routes/api/hello.ts
159 export function GET() {
160 return new Response(process.env.API_BASE ?? "unset");
161 }
162 ```
163
164 Values prefixed `VITE_` are inlined into the client bundle at build
165 time instead, as `import.meta.env.VITE_*` — set those in the shell
166 that runs `alchemy deploy`, not in `env`.
167
168 ## Prerendering
169
170 Nitro renders the routes you list at build time into `.output/public`.
171 They are baked into the image and served as static files with no
172 handler invocation:
173
174 ```typescript
175 export const Website = Fly.Website.SolidStart("Website", {
176 nitro: { prerender: { routes: ["/", "/about"] } },
177 });
178 ```
179
180 `prerender` takes the routes to render (`routes`) and can crawl links
181 from prerendered pages to prerender them too (`crawlLinks`). The
182 `nitro` prop is the home for all nitro options (route rules, storage,
183 ...) — the integration owns the plugin instance, so they cannot live
184 in `vite.config.ts`. Values must be JSON-serializable; `preset` is
185 owned by the Node deploy target, and a foreign preset is a hard error.
186
187 ## Local dev
188
189 ```sh
190 bun alchemy dev
191 ```
192
193 `alchemy dev` runs SolidStart's own Vite dev server (native HMR)
194 instead of deploying; `site.url` is the local address and no Fly
195 resources are created. Nitro plays no part in dev. Wrap the site in
196 `Alchemy.remote()` to deploy the live App and Service even during
197 dev:
198
199 ```typescript
200 export const Website = Fly.Website.SolidStart("Website").pipe(
201 Alchemy.remote(),
202 );
203 ```
204
205 SolidStart's plugin resolves its app root and route directory from
206 the process working directory, so one `alchemy dev` process serves
207 one SolidStart app at a time.
208
209 :::caution[Run `alchemy dev` under Node]
210 SolidStart 2's dev server answers requests through `srvx/node`, which
211 returns the string `[object Object]` instead of the rendered document
212 when it runs under Bun. Production builds are unaffected — only the
213 dev server is. Until that upstream gap closes, run `alchemy dev` with
214 Node (`npx alchemy dev`) for SolidStart projects.
215 :::
216
217 ## Custom domain
218
219 ```typescript
220 const site = yield* Fly.Website.SolidStart("Web", {
221 domain: "app.example.com",
222 });
223 ```
224
225 `domain` requests ACME (`Fly.Certificate`) on the App. `url`
226 becomes `https://app.example.com`. Point DNS at the App first — v1
227 does not create DNS records.
228
229 ## Where next
230
231 - [SolidStart API reference](/providers/fly/website/solidstart)
232 - [Apps](/fly/compute/apps) and [Services](/fly/compute/services)
233 - [IPs & certificates](/fly/networking)