Skip to content

Vinext

Archil.Website.Vinext deploys a vinext app to an Archil sandbox, as a long-running Node process (vinext build, then startProdServer). 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”

Keep vinext, react, react-dom, and react-server-dom-webpack in your application dependencies, with vite and @vitejs/plugin-rsc for building. Add the Alchemy integration:

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

Configure vinext

Section titled “Configure vinext”
vite.config.ts
import { defineConfig } from "vite";
import vinext from "vinext";


export default defineConfig({
  plugins: [vinext({ prerender: true })],
});

Alchemy injects the target-specific data-cache adapter during deployment. No Alchemy plugin is required in vite.config.ts; deployment settings belong on Website.Vinext. Leave Cloudflare plugins and Worker entrypoints out of this application.

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.Vinext("Website");

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

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


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

Add environment variables

Section titled “Add environment variables”
export const Website = Archil.Website.Vinext("Website", {
  env: { GREETING: "Hello from vinext on Archil!" },
});

env is available during build, development, and production. Server code reads process.env; public framework variables may be compiled into browser assets. Keep secrets out of public keys and wrap credentials in Redacted.

Read the runtime environment

Section titled “Read the runtime environment”
app/api/hello/route.ts
export function GET(request: Request) {
  const name = new URL(request.url).searchParams.get("name") ?? "world";
  return Response.json({ name, greeting: process.env.GREETING ?? "hello" });
}

Request-dependent route handlers read the production environment. A prerendered page reflects its build-time inputs instead.

Configure the data cache

Section titled “Configure the data cache”

The default data cache is process-local. To persist ISR and "use cache" across restarts, supply an existing Redis endpoint through env.REDIS_URL. The Website does not install or provision Redis. Protect credentials with Redacted.make and keep the Redis service private.

Local development

Section titled “Local development”
Terminal window
bun alchemy dev

The Website runs vinext dev with native HMR and creates no cloud resources. Other resources declared in the Stack retain their own provider behavior. Apply .pipe(Alchemy.remote()) to the Website for a live deployment during dev.

Where next

Section titled “Where next”