The best way to control Claude Code, Codex and more from any computer or phone

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