Skip to content

Vite

Archil.Website.Vite deploys a Vite app to an Archil sandbox, as static assets from vite build, served by a small static-file server. The site is the program of its own sandbox, on port 3000, at a public https://3000-…archil.app URL. A stopped sandbox starts again on the next request.

Install

Section titled “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:

Terminal window
pnpm add -D https://pkg.alchemy.run/@alchemy.run/frontend-frameworks/pr:2930:d8eb8a5

Configure Vite

Section titled “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

Section titled “Declare the Website”

Declare the site as a module-level const:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";


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

sandbox sizes the site’s sandbox and sets its image, timeouts, disks and network policy:

alchemy.run.ts
export const Website = Archil.Website.Vite("Website", {
  sandbox: { vcpuCount: 2, memSizeMiB: 4096, idleTtlSeconds: 600 },
});

Add it to the Stack

Section titled “Add it to the Stack”

Yield the site from your Stack and return its URL:

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


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


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

Run alchemy deploy. url is the site’s https://3000-…archil.app URL. site.sandbox is the sandbox behind it, and undefined under alchemy dev.

See examples/archil-website-vite for the checked-in example.

Add environment variables

Section titled “Add environment variables”

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

alchemy.run.ts
export const Website = Archil.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

Section titled “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

Section titled “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 = Archil.Website.Vite("Docs", {
  assets: { notFoundHandling: "404-page" },
});

Vite configuration

Section titled “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 = Archil.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

Section titled “Local development”

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

Where next

Section titled “Where next”