@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 234 lines 6.96 KB
Raw
1 ---
2 title: SolidStart
3 description: Deploy a SolidStart app to Railway with Railway.Website.SolidStart — nitro's node preset on a container Service, prerendered pages in 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 `Railway.Website.SolidStart` deploys a
13 [SolidStart](https://start.solidjs.com) app to Railway. It runs your
14 project's own `vite build` and appends nitro's `node` preset: the SSR
15 server plus client assets (prerendered pages included) run on one
16 [`Railway.Service`](/railway/compute/services). Alchemy creates a
17 [`Railway.Project`](/railway/compute/projects) if you omit
18 `project`. The URL is the generated `*.up.railway.app` hostname. No
19 adapter.
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 Railway from "@alchemy.run/railway";
73
74 export const Website = Railway.Website.SolidStart("Website");
75 ```
76
77 Pass `project` to put the Service in an existing `Railway.Project`.
78 `rootDir` is the project root — the directory holding `package.json`
79 and `vite.config.*`. It defaults to `"."`, so set it only when the app
80 does not sit next to `alchemy.run.ts`:
81
82 ```typescript
83 export const Website = Railway.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: Railway.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://{name}.up.railway.app`. `site.service`
111 and `site.project` are the Railway resources underneath —
112 `undefined` during `alchemy dev`.
113
114 See the
115 [SolidStart API reference](/providers/railway/website/solidstart)
116 for every prop and attribute.
117
118 ## Add environment variables
119
120 Process environment is a top-level `env` map — plain strings, or
121 `Redacted` values:
122
123 ```diff lang="typescript"
124 // alchemy.run.ts
125 export const Website = Railway.Website.SolidStart("Website", {
126 + env: {
127 + API_BASE: "https://api.example.com",
128 + },
129 });
130 ```
131
132 The values are copied onto `process.env` before the build and the
133 dev server, and onto the Service at deploy time, so server code
134 reads the same keys in both modes. Client inlining is whatever Vite
135 does (`VITE_` prefixes).
136
137 An output from another resource only exists once that resource is
138 yielded, so declare the site inside the Stack generator instead:
139
140 ```typescript
141 // alchemy.run.ts
142 Effect.gen(function* () {
143 const api = yield* Api;
144
145 const site = yield* Railway.Website.SolidStart("Website", {
146 env: { API_BASE: api.url },
147 });
148
149 return { url: site.url };
150 });
151 ```
152
153 ## Read the environment in server code
154
155 The SolidStart server is a plain Node process, so API routes,
156 server functions, and SSR read the environment from `process.env`:
157
158 ```typescript
159 // src/routes/api/hello.ts
160 export function GET() {
161 return new Response(process.env.API_BASE ?? "unset");
162 }
163 ```
164
165 Values prefixed `VITE_` are inlined into the client bundle at build
166 time instead, as `import.meta.env.VITE_*` — set those in the shell
167 that runs `alchemy deploy`, not in `env`.
168
169 ## Prerendering
170
171 Nitro renders the routes you list at build time into `.output/public`.
172 They are baked into the Service image and served as static files with
173 no handler invocation:
174
175 ```typescript
176 export const Website = Railway.Website.SolidStart("Website", {
177 nitro: { prerender: { routes: ["/", "/about"] } },
178 });
179 ```
180
181 `prerender` takes the routes to render (`routes`) and can crawl links
182 from prerendered pages to prerender them too (`crawlLinks`). The
183 `nitro` prop is the home for all nitro options (route rules, storage,
184 ...) — the integration owns the plugin instance, so they cannot live
185 in `vite.config.ts`. Values must be JSON-serializable; `preset` is
186 owned by the Node deploy target, and a foreign preset is a hard error.
187
188 ## Local dev
189
190 ```sh
191 bun alchemy dev
192 ```
193
194 `alchemy dev` runs SolidStart's own Vite dev server (native HMR)
195 instead of deploying; `site.url` is the local address and no Railway
196 resources are created. Nitro plays no part in dev. Wrap the site in
197 `Alchemy.remote()` to deploy the live Service even during dev:
198
199 ```typescript
200 export const Website = Railway.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* Railway.Website.SolidStart("Web", {
221 domain: "app.example.com",
222 });
223 ```
224
225 `domain` attaches a [`Railway.CustomDomain`](/railway/networking)
226 (`targetPort` 3000). `url` becomes `https://app.example.com`
227 instead of the generated `*.up.railway.app`.
228
229 ## Where next
230
231 - [SolidStart API reference](/providers/railway/website/solidstart)
232 - [Projects](/railway/compute/projects) and
233 [Services](/railway/compute/services)
234 - [Custom domains](/railway/networking)