sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ hetzner/ frontend/ vite.mdx

import PackageManagers from "../../../../components/PackageManagers.astro";
export const devDeps = "@alchemy.run/frontend-frameworks";

Hetzner.Website.Vite deploys a Vite project to a Hetzner Cloud Server. It runs vite build and serves the output from a systemd Service on port 3000. Omit server and Alchemy creates a cpx12 / ubuntu-24.04 Server in fsn1. Live url is http://{ipv4}:3000. Your vite.config.* loads natively — plugins included. There is no TLS on the Service and no framework server module.

React, Vue, and Solid client SPAs belong here, as do multi-page apps that emit one HTML file per route. SSR frameworks that wrap Vite deploy through their own composites — Astro, Nextjs, Nuxt, ReactRouter, SolidStart, SvelteKit, TanStackStart, Waku, Octane.

Install

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads its /vite and /vite/node exports from your project at deploy time. It is only used at build time, so a dev dependency is enough:

Configure Vite

Your vite.config.* file loads natively — React, Vue, or Solid plugins, Tailwind, and any other non-serializable options work exactly as they do outside Alchemy. Alchemy merges a programmatic config over it via the vite prop — see Vite configuration below.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Do not set a Vite SSR adapter. This composite never creates a framework server module — it only ships the client build.

Declare the Website

Declare the site as a module-level const (rather than inline in the Stack):

// alchemy.run.ts
import * as Hetzner from "@alchemy.run/hetzner";

export const Website = Hetzner.Website.Vite("Website");

Pass server to run the unit on a Server you already have — several Services can share one machine; this site always listens on port 3000:

export const Box = Hetzner.Server("Box", {
  serverType: "cpx12",
  image: "ubuntu-24.04",
  location: "fsn1",
});

export const Website = Hetzner.Website.Vite("Website", { server: Box });

Add it to the Stack

Yield the site from your Stack and return its URL:

// alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyViteSite",
  {
    providers: Hetzner.providers(),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

On deploy, url is http://{ipv4}:3000. server and service are the backing resources; they are undefined under alchemy dev.

See examples/hetzner-website-vite for the checked-in example (API unit and static site on one cpx12).

Add environment variables

env is process environment — set on process.env before vite build / alchemy dev, and on the systemd unit at deploy. It is not Worker bindings:

// alchemy.run.ts
export const Website = Hetzner.Website.Vite("Website", {
+  env: {
+    VITE_GREETING: "Hello from Alchemy!",
+  },
});

Vite inlines VITE_* into the client bundle at build time. Other keys reach the hosted Node process but not the browser.

Read the environment

Client code reads inlined values from import.meta.env:

// src/main.ts
const greeting = import.meta.env.VITE_GREETING ?? "hello";

Single-page vs multi-page

Plain Vite apps are typically SPAs, so assets.notFoundHandling defaults to "single-page-application": unmatched paths get index.html with status 200 so client-side routes deep-link. Use "404-page" for multi-page sites that ship a 404.html:

export const Website = Hetzner.Website.Vite("Docs", {
  assets: { notFoundHandling: "404-page" },
});

Vite configuration

rootDir is the project root (the directory containing package.json). Default ".".

vite.outDir and vite.base are serializable overrides merged over the config file:

export const Website = Hetzner.Website.Vite("Website", {
  rootDir: "./app",
  vite: { outDir: "build", base: "/docs/" },
});

outDir is relative to rootDir and defaults to the file's build.outDir (Vite's default: "dist"). base is Vite's public base path.

Local development

alchemy dev runs Vite's own dev server (native HMR) instead of deploying; site.url is the local address and no Server or Service is created. Wrap the site in Alchemy.remote() to deploy the real infrastructure even during dev.

Custom domain

domain is a hostname string. It requires zone — an existing Hetzner.Zone. Alchemy creates an A RecordSet pointing at the Server's public IPv4. url becomes http://{domain}:3000. Passing domain without zone fails. The Service does not terminate TLS:

export const Dns = Hetzner.Zone("dns", { name: "example.com" });

export const Website = Hetzner.Website.Vite("Website", {
  domain: "app.example.com",
  zone: Dns,
});

Where next