@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 215 lines 6.28 KB
Raw
1 ---
2 title: Vite
3 description: "Deploy a Vite SPA to Hetzner with Hetzner.Website.Vite — static assets as a systemd unit on a Server, http://{ipv4}:3000, and Vite's own dev server under alchemy dev."
4 sidebar:
5 order: 2
6 ---
7
8 import PackageManagers from "../../../../components/PackageManagers.astro";
9
10 export const devDeps = "@alchemy.run/frontend-frameworks";
11
12 `Hetzner.Website.Vite` deploys a [Vite](https://vite.dev) project to
13 a Hetzner Cloud Server. It runs `vite build` and serves the output
14 from a systemd [`Service`](/hetzner/compute/services) on port 3000.
15 Omit `server` and Alchemy creates a `cpx12` / `ubuntu-24.04`
16 [`Server`](/hetzner/compute/servers) in `fsn1`. Live `url` is
17 `http://{ipv4}:3000`. Your `vite.config.*` loads natively — plugins
18 included. There is no TLS on the Service and no framework server
19 module.
20
21 React, Vue, and Solid client SPAs belong here, as do multi-page apps
22 that emit one HTML file per route. SSR frameworks that wrap Vite
23 deploy through their own composites —
24 [`Astro`](/hetzner/frontend/astro),
25 [`Nextjs`](/hetzner/frontend/nextjs),
26 [`Nuxt`](/hetzner/frontend/nuxt),
27 [`ReactRouter`](/hetzner/frontend/react-router),
28 [`SolidStart`](/hetzner/frontend/solidstart),
29 [`SvelteKit`](/hetzner/frontend/sveltekit),
30 [`TanStackStart`](/hetzner/frontend/tanstack-start),
31 [`Waku`](/hetzner/frontend/waku),
32 [`Octane`](/hetzner/frontend/octane).
33
34 ## Install
35
36 The build integration is not bundled with alchemy. Install
37 `@alchemy.run/frontend-frameworks`; the resource loads its `/vite`
38 and `/vite/node` exports from your project at deploy time. It is
39 only used at build time, so a dev dependency is enough:
40
41 <PackageManagers dev={devDeps} />
42
43 ## Configure Vite
44
45 Your `vite.config.*` file loads natively — React, Vue, or Solid
46 plugins, Tailwind, and any other non-serializable options work
47 exactly as they do outside Alchemy. Alchemy merges a programmatic
48 config *over* it via the `vite` prop — see
49 [Vite configuration](#vite-configuration) below.
50
51 ```typescript
52 // vite.config.ts
53 import { defineConfig } from "vite";
54 import react from "@vitejs/plugin-react";
55 import tailwindcss from "@tailwindcss/vite";
56
57 export default defineConfig({
58 plugins: [react(), tailwindcss()],
59 });
60 ```
61
62 Do not set a Vite SSR adapter. This composite never creates a
63 framework server module — it only ships the client build.
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 Hetzner from "@alchemy.run/hetzner";
73
74 export const Website = Hetzner.Website.Vite("Website");
75 ```
76
77 Pass `server` to run the unit on a Server you already have —
78 several Services can share one machine; this site always listens on
79 port 3000:
80
81 ```typescript
82 export const Box = Hetzner.Server("Box", {
83 serverType: "cpx12",
84 image: "ubuntu-24.04",
85 location: "fsn1",
86 });
87
88 export const Website = Hetzner.Website.Vite("Website", { server: Box });
89 ```
90
91 ## Add it to the Stack
92
93 Yield the site from your Stack and return its URL:
94
95 ```typescript
96 // alchemy.run.ts
97 import * as Alchemy from "alchemy";
98 import * as Effect from "effect/Effect";
99
100 export default Alchemy.Stack(
101 "MyViteSite",
102 {
103 providers: Hetzner.providers(),
104 state: Alchemy.localState(),
105 },
106 Effect.gen(function* () {
107 const site = yield* Website;
108 return { url: site.url };
109 }),
110 );
111 ```
112
113 On deploy, `url` is `http://{ipv4}:3000`. `server` and `service` are
114 the backing resources; they are `undefined` under `alchemy dev`.
115
116 See
117 [examples/hetzner-website-vite](https://github.com/alchemy-run/alchemy/tree/main/examples/hetzner-website-vite)
118 for the checked-in example (API unit and static site on one
119 `cpx12`).
120
121 ## Add environment variables
122
123 `env` is process environment — set on `process.env` before
124 `vite build` / `alchemy dev`, and on the systemd unit at deploy. It
125 is not Worker bindings:
126
127 ```diff lang="typescript"
128 // alchemy.run.ts
129 export const Website = Hetzner.Website.Vite("Website", {
130 + env: {
131 + VITE_GREETING: "Hello from Alchemy!",
132 + },
133 });
134 ```
135
136 Vite inlines `VITE_*` into the client bundle at build time. Other
137 keys reach the hosted Node process but not the browser.
138
139 ## Read the environment
140
141 Client code reads inlined values from `import.meta.env`:
142
143 ```typescript
144 // src/main.ts
145 const greeting = import.meta.env.VITE_GREETING ?? "hello";
146 ```
147
148 ## Single-page vs multi-page
149
150 Plain Vite apps are typically SPAs, so `assets.notFoundHandling`
151 defaults to `"single-page-application"`: unmatched paths get
152 `index.html` with status 200 so client-side routes deep-link. Use
153 `"404-page"` for multi-page sites that ship a `404.html`:
154
155 ```typescript
156 export const Website = Hetzner.Website.Vite("Docs", {
157 assets: { notFoundHandling: "404-page" },
158 });
159 ```
160
161 ## Vite configuration
162
163 `rootDir` is the project root (the directory containing
164 `package.json`). Default `"."`.
165
166 `vite.outDir` and `vite.base` are serializable overrides merged
167 *over* the config file:
168
169 ```typescript
170 export const Website = Hetzner.Website.Vite("Website", {
171 rootDir: "./app",
172 vite: { outDir: "build", base: "/docs/" },
173 });
174 ```
175
176 `outDir` is relative to `rootDir` and defaults to the file's
177 `build.outDir` (Vite's default: `"dist"`). `base` is Vite's public
178 base path.
179
180 ## Local development
181
182 `alchemy dev` runs Vite's own dev server (native HMR) instead of
183 deploying; `site.url` is the local address and no Server or Service
184 is created. Wrap the site in `Alchemy.remote()` to deploy the real
185 infrastructure even during dev.
186
187 ## Custom domain
188
189 `domain` is a hostname string. It requires `zone` — an existing
190 [`Hetzner.Zone`](/hetzner/networking/dns). Alchemy creates an A
191 [`RecordSet`](/hetzner/networking/dns) pointing at the Server's
192 public IPv4. `url` becomes `http://{domain}:3000`. Passing `domain`
193 without `zone` fails. The Service does not terminate TLS:
194
195 ```typescript
196 export const Dns = Hetzner.Zone("dns", { name: "example.com" });
197
198 export const Website = Hetzner.Website.Vite("Website", {
199 domain: "app.example.com",
200 zone: Dns,
201 });
202 ```
203
204 ## Where next
205
206 - [`Hetzner.Website.Vite` API](/providers/hetzner/website/vite)
207 - [Astro](/hetzner/frontend/astro),
208 [Next.js](/hetzner/frontend/nextjs),
209 [Nuxt](/hetzner/frontend/nuxt),
210 [SvelteKit](/hetzner/frontend/sveltekit),
211 [Waku](/hetzner/frontend/waku),
212 [Octane](/hetzner/frontend/octane) — SSR frameworks
213 - [Servers](/hetzner/compute/servers),
214 [Services](/hetzner/compute/services),
215 [DNS](/hetzner/networking/dns)