Skip to content

Vocs

Archil.Website.Vocs deploys a Vocs app to an Archil sandbox, as prerendered pages, served extensionless (/about → about/index.html). 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 /vocs/node 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

Your Vocs project already needs vocs installed.

Configure Vocs

Section titled “Configure Vocs”

Your vocs.config.* file loads natively — title, sidebar, and any other Vocs options work exactly as they do outside Alchemy:

vocs.config.ts
import { defineConfig } from "vocs/config";


export default defineConfig({
  title: "Docs",
  sidebar: [
    { text: "Home", link: "/" },
    { text: "Guide", link: "/guide" },
  ],
});

If vocs.config.* sets outDir, pass the same value on the resource (default "dist") so generated output stays outside the rebuild hash:

export const Website = Archil.Website.Vocs("Website", {
  rootDir: "./docs",
  outDir: "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.Vocs("Website");

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

alchemy.run.ts
export const Website = Archil.Website.Vocs("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.Vocs("Website");


export default Alchemy.Stack(
  "MyVocsSite",
  {
    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-vocs for the checked-in example.

Add environment variables

Section titled “Add environment variables”

Top-level env is copied onto process.env before build and alchemy dev, and onto the program at deploy:

alchemy.run.ts
export const Website = Archil.Website.Vocs("Website", {
  rootDir: "./docs",
  env: {
    DOCS_TITLE: "Hello from Alchemy!",
  },
});

These are process environment variables, not Worker bindings.

Read the environment

Section titled “Read the environment”

Vocs prerenders at build time, so page content that reads process.env is baked into the HTML. The same values are set on the hosted Node process; there is no request-time Vocs server.

const title = process.env.DOCS_TITLE ?? "Docs";

Local development

Section titled “Local development”

alchemy dev runs Vocs’ own dev server (native HMR) instead of deploying; site.url is the local address and no Archil resources are created (sandbox is undefined). Wrap the site in Alchemy.remote() to deploy the live sandbox even during dev:

export const Website = Archil.Website.Vocs("Website", {
  rootDir: "./docs",
}).pipe(Alchemy.remote());

Where next

Section titled “Where next”