Skip to content

Static sites

Archil.Website.StaticSite runs your build command and serves the output directory from a small static-file server (GET assets, /health, optional SPA or 404 page). It runs as the program of its own Archil.Sandbox, at a public https://3000-…archil.app URL. Use it for Hugo, Zola, Eleventy, or any custom pipeline; for Vite projects, use Archil.Website.Vite.

Declare the Website

Section titled “Declare the Website”

command and outdir are required:

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


export const Website = Archil.Website.StaticSite("Website", {
  command: "hugo --minify",
  outdir: "public",
});

The build is a Command.Build: unchanged inputs skip it (details). Narrow what it hashes with memo: { include: [...] }, or set memo: false to build on every deploy.

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.StaticSite("Website", {
  command: "hugo --minify",
  outdir: "public",
});


export default Alchemy.Stack(
  "MyStaticSite",
  { 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.

Size the sandbox

Section titled “Size the sandbox”

sandbox sets the site’s sandbox: size, image, timeouts and network policy:

alchemy.run.ts
export const Website = Archil.Website.StaticSite("Website", {
  command: "hugo --minify",
  outdir: "public",
  sandbox: { idleTtlSeconds: 0 },
});

Build from a subdirectory

Section titled “Build from a subdirectory”

cwd is where command runs, and outdir is relative to it:

export const Website = Archil.Website.StaticSite("Web", {
  cwd: "apps/web",
  command: "npm run build",
  outdir: "dist",
});

Serve an SPA or a 404 page

Section titled “Serve an SPA or a 404 page”

spa: true answers a request that matches no file with index.html and a 200, so the client-side router takes over:

export const App = Archil.Website.StaticSite("App", {
  command: "npm run build",
  outdir: "dist",
  spa: true,
});

errorPage answers it with your page and a real 404 instead. Passing both fails the deploy:

export const Docs = Archil.Website.StaticSite("Docs", {
  command: "hugo --minify",
  outdir: "public",
  errorPage: "404.html",
});

Set environment variables

Section titled “Set environment variables”

env reaches the build command and the program’s process:

alchemy.run.ts
export const Website = Archil.Website.StaticSite("Website", {
  command: "hugo --minify",
  outdir: "public",
  env: { HUGO_ENV: "production" },
});

Develop locally

Section titled “Develop locally”

Under alchemy dev, dev.command runs instead of the build, and site.url is the address it prints (dev.url sets it when it can’t be detected):

export const Website = Archil.Website.StaticSite("Website", {
  command: "hugo --minify",
  outdir: "public",
  dev: { command: "hugo server" },
});

Without dev, the site builds and a local static server serves outdir. Wrap it in Alchemy.remote() to deploy the live sandbox even during dev.

Where next

Section titled “Where next”