Skip to content

React Router

Archil.Website.ReactRouter deploys a React Router app to an Archil sandbox, in framework mode, built through your own vite build; the SSR server serves the client assets first. 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 /react-router and /react-router/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:0cabab6

The React Router side is whatever npx create-react-router@latest scaffolds — react-router, @react-router/dev, @react-router/node, isbot, and vite. Keep @react-router/node and isbot in dependencies: React Router picks its default entry.server by reading them from your package.json, and installs isbot on the fly if it is missing.

Configure Vite

Section titled “Configure Vite”

Your vite.config.ts stays what the React Router scaffold gives you — no adapter, no server preset. Vite plugins like Tailwind go in plugins as usual:

vite.config.ts
import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";


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

reactRouter() owns routing, typegen, and both build environments. Alchemy drives the same two passes react-router build runs, wraps the server manifest with createRequestHandler, and packages the resulting fetch handler as a Node HTTP server on port 3000.

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

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

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


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

How the two build outputs are deployed

Section titled “How the two build outputs are deployed”

react-router build writes two directories, and both land in the sandbox:

build/
├── client/    -> uploaded with the program, served first
└── server/    -> wrapped as a Node HTTP server on port 3000

build/client holds the hashed browser bundles plus everything you put in public/. build/server/index.js is a ServerBuild manifest, not a request handler, so Alchemy wraps it with createRequestHandler during the build and emits a Node serve entry — that process is the sandbox’s program.

If you set Vite’s base, set React Router’s basename to the same prefix: the client directory maps onto the site root one-for-one, so the paths the SSR document emits have to be the paths the program was given.

Add environment variables

Section titled “Add environment variables”

Process environment is a top-level env map — plain strings, or Redacted values:

alchemy.run.ts
export const Website = Archil.Website.ReactRouter("Website", {
  env: {
    API_BASE: "https://api.example.com",
  },
});

The values are copied onto process.env before the build and the dev server, and onto the program at deploy time, so server code reads the same keys in both modes. Client inlining is whatever Vite does (VITE_ prefixes).

An output from another resource only exists once that resource is yielded, so declare the site inside the Stack generator instead:

alchemy.run.ts
Effect.gen(function* () {
  const api = yield* Api;


  const site = yield* Archil.Website.ReactRouter("Website", {
    env: { API_BASE: api.url },
  });


  return { url: site.url };
});

Read the environment in a loader

Section titled “Read the environment in a loader”

The React Router server is a plain Node process. Loaders and actions read the environment from process.env:

app/routes/home.tsx
export function loader() {
  return { apiBase: process.env.API_BASE ?? "unset" };
}

Values prefixed VITE_ are inlined into the client bundle at build time instead, as import.meta.env.VITE_* — set those in the shell that runs alchemy deploy, not in env.

Read the environment in a resource route

Section titled “Read the environment in a resource route”

A route module with no default export is a resource route, served by the same Node process:

app/routes/api.hello.ts
export function loader() {
  return new Response(process.env.API_BASE ?? "unset");
}

Build configuration

Section titled “Build configuration”

The build runs through your project’s own vite.config.ts and react-router.config.ts. A custom buildDirectory just works — the integration observes the directory from the resolved Vite config, so there is nothing to mirror on the resource.

Local dev

Section titled “Local dev”
Terminal window
bun alchemy dev

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

export const Website = Archil.Website.ReactRouter("Website").pipe(
  Alchemy.remote(),
);

React Server Components

Section titled “React Server Components”

RSC is not supported yet. React Router’s unstable RSC plugin — and the future.v8_viteEnvironmentApi flag — emit more than one server environment, and this resource assembles a single Node entry. A build that produces no single server entry fails with an actionable error rather than deploying something broken.

Where next

Section titled “Where next”