import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import * as Schedule from "effect/Schedule";
import * as FrameworkCore from "../core/index.ts";
import {
Framework,
FrameworkError,
type DeployTarget,
type DeployTargetInput,
} from "../core/index.ts";
/**
* The structural slice of the project's `vite` module this package drives.
* Typed structurally so the package carries no dependency on vite — the
* *project's* install is always the one loaded.
*
* `build` (not `createBuilder`) is the entry point: the integration drives a
* two-pass build — `vite build` for the `client` environment, then `vite
* build` with `build.ssr` for the server environment — which is what
* `react-router build` runs. React Router 8 always builds through the Vite
* Environment API, so the server pass's overrides are declared on the `ssr`
* environment as well (see {@link inlineServerBuildConfig}).
*/
export interface ReactRouterViteModule {
readonly version?: string;
readonly build: (config: Record<string, unknown>) => Promise<unknown>;
readonly createServer: (config: Record<string, unknown>) => Promise<ReactRouterViteDevServer>;
}
/** The structural slice of a Vite dev server this package reads. */
export interface ReactRouterViteDevServer {
readonly listen: () => Promise<unknown>;
readonly close: () => Promise<void>;
readonly resolvedUrls?: { readonly local: ReadonlyArray<string> } | null | undefined;
}
/** The slice of a resolved Vite config the output-directory capture reads. */
export interface ResolvedViteBuildSlice {
readonly root: string;
readonly build: { readonly outDir: string };
}
/**
* The configuration this package assembles from {@link ReactRouterOptions}
* and hands to a deploy-target factory. The target treats it as its
* `DeployTarget.config`; the framework half never inspects a resolved
* target's config.
*/
export interface ReactRouterTargetConfig {
/**
* Build output directory relative to the project root — the parent of
* `client/` and `server/`. Mirrors `react-router.config.ts`'s
* `buildDirectory`, and is only a FALLBACK: the integration prefers the
* directories it observes on the resolved Vite config.
* @default "build"
*/
readonly buildDirectory?: string | undefined;
}
/**
* A deploy target for React Router: the generic `DeployTarget` seams plus
* the one framework-specific hook the build needs — the file name of the
* server entry the server build emits, which the target's finishing pass
* wraps.
*/
export interface ReactRouterTarget extends DeployTarget<ReactRouterTargetConfig> {
/**
* The server entry file name within the server output directory. React
* Router names it after `react-router.config.ts`'s `serverBuildFile`
* (default `index.js`). Omitted targets fall back to
* {@link DEFAULT_SERVER_BUILD_FILE}, and a build that emits exactly one
* top-level module under the server directory uses that instead when the
* expected name is absent.
*/
readonly serverEntryFileName?: string | undefined;
}
/**
* How a deploy target is passed to this package: a `ReactRouterTarget`
* value, a factory `(config) => ReactRouterTarget`, or a module specifier
* resolved from the *project's* `node_modules`.
*/
export type ReactRouterTargetInput = DeployTargetInput<ReactRouterTarget, ReactRouterTargetConfig>;
/**
* The default deploy target: this package's own AWS Lambda target module,
* loaded from the project's dependency tree. (Cloudflare deploys React
* Router through its native Vite integration — `Cloudflare.Website.Vite` —
* so no Cloudflare target exists here.)
*/
export const DEFAULT_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/react-router/aws";
/** The Vite plugin package a React Router project must install. */
export const REACT_ROUTER_PLUGIN_SPECIFIER = "@react-router/dev";
/** The default root output directory (the parent of `client/` and `server/`). */
export const DEFAULT_BUILD_DIRECTORY = "build";
/** The default server entry file name inside the server output directory. */
export const DEFAULT_SERVER_BUILD_FILE = "index.js";
/**
* React Router's own virtual module holding the compiled server build — the
* `ServerBuild` manifest (`{ entry, routes, assets, basename, ... }`), NOT a
* request handler.
*/
export const REACT_ROUTER_SERVER_BUILD_ID = "virtual:react-router/server-build";
/**
* The virtual module this integration makes the server build's rollup input:
* it turns the `ServerBuild` manifest into a web-standard fetch handler.
*/
export const SERVER_ENTRY_ID = "virtual:alchemy/react-router-server-entry";
/** Rollup's convention for a plugin-owned virtual module id. */
const RESOLVED_SERVER_ENTRY_ID = `\0${SERVER_ENTRY_ID}`;
export interface ReactRouterOptions {
/**
* Project root (the directory containing `vite.config.*`).
* @default process.cwd()
*/
readonly root?: string | undefined;
/**
* The deploy target the build is produced for. Accepts a target value, a
* `(config) => target` factory, or a module specifier string.
* @default "@alchemy.run/frontend-frameworks/react-router/aws"
*/
readonly target?: ReactRouterTargetInput | undefined;
/**
* Build output directory relative to the project root — the parent of
* `client/` and `server/`. Mirrors `react-router.config.ts`'s
* `buildDirectory`; used only as a fallback when the resolved Vite config
* could not be observed.
* @default "build"
*/
readonly buildDirectory?: string | undefined;
readonly dev?:
| {
/** Default dev-server port (overridden by `FrameworkDevOptions.port`). */
readonly port?: number | undefined;
}
| undefined;
}
const fail = (message: string, cause?: unknown) =>
new FrameworkError({ framework: "react-router", message, cause });
/**
* The source of the virtual server entry ({@link SERVER_ENTRY_ID}).
*
* React Router's server build is a manifest, not a handler: it has no
* default export and nothing to call. `createRequestHandler` from
* `react-router` turns it into `(request) => Promise<Response>`, and this
* module exposes that as the `{ fetch }` shape every deploy target's
* finishing pass already knows how to wrap.
*
* This wrapping happens at BUILD time (as the server build's rollup input)
* rather than as a file emitted afterwards, because `react-router` itself
* must be part of the emitted bundle — the deployed server directory ships
* without a `node_modules` tree.
*/
export const serverEntrySource = (mode: string = "production"): string =>
`// Auto-generated by @alchemy.run/frontend-frameworks/react-router — do not edit.
import * as build from "${REACT_ROUTER_SERVER_BUILD_ID}";
import { createRequestHandler } from "react-router";
const handleRequest = createRequestHandler(build, ${JSON.stringify(mode)});
export default {
fetch(request) {
return handleRequest(request);
},
};
`;
/** The structural slice of a Vite plugin this integration constructs. */
export interface InlineVitePlugin {
readonly name: string;
readonly enforce?: "pre" | "post" | undefined;
readonly resolveId?: ((id: string) => string | undefined) | undefined;
readonly load?: ((id: string) => string | undefined) | undefined;
readonly configResolved?: ((config: ResolvedViteBuildSlice) => void) | undefined;
}
/**
* The Vite plugin serving {@link SERVER_ENTRY_ID}. `enforce: "pre"` so the
* virtual id resolves before any project plugin sees it.
*/
export const serverEntryPlugin = (options?: {
readonly mode?: string | undefined;
}): InlineVitePlugin => ({
name: "alchemy:react-router-server-entry",
enforce: "pre",
resolveId: (id) => (id === SERVER_ENTRY_ID ? RESOLVED_SERVER_ENTRY_ID : undefined),
load: (id) => (id === RESOLVED_SERVER_ENTRY_ID ? serverEntrySource(options?.mode) : undefined),
});
/** A mutable slot the {@link captureOutDirPlugin} writes the resolved outDir into. */
export interface OutDirCapture {
outDir?: string | undefined;
}
/**
* The Vite plugin that observes the RESOLVED output directory of a build.
*
* React Router derives both output directories from `react-router.config.ts`
* (`buildDirectory`), which is TypeScript the integration must not evaluate
* itself. Reading them off the config Vite actually resolved is exact, free,
* and honors every project override.
*/
export const captureOutDirPlugin = (capture: OutDirCapture): InlineVitePlugin => ({
name: "alchemy:react-router-capture-outdir",
enforce: "post",
configResolved: (config) => {
capture.outDir = config.build.outDir;
},
});
/**
* The inline config for the CLIENT pass, merged over the project's own
* `vite.config.*` (which loads natively, plugins included).
*/
export const inlineClientBuildConfig = (
root: string,
plugins: ReadonlyArray<InlineVitePlugin>,
): Record<string, unknown> => ({
root,
mode: "production",
// Warn-level: rolldown-vite's native progress reporter writes straight to
// the fd, corrupting hosting-process reporters that can only intercept
// JS-level writers.
logLevel: "warn",
plugins,
});
/**
* The inline config for the SERVER pass.
*
* Two overrides carry the whole AWS story:
*
* - `build.ssr` selects React Router's server environment (the flag its
* plugin branches on), and `build.rollupOptions.input` replaces the
* framework's `virtual:react-router/server-build` input with the fetch
* handler wrapper ({@link serverEntrySource}) — the plugin honors a
* user-provided input verbatim.
* - `noExternal` is load-bearing: Vite externalizes `node_modules` imports
* from SSR bundles by default, so a stock React Router server build emits
* `import { ServerRouter } from "react-router"` and is only runnable next
* to an installed dependency tree. A Lambda ships the server directory
* alone, so the bundle must be self-contained — only `node:` builtins
* stay external. Declared on both the legacy `ssr` key and the
* environment key so it holds across Vite majors.
*/
export const inlineServerBuildConfig = (
root: string,
plugins: ReadonlyArray<InlineVitePlugin>,
): Record<string, unknown> => ({
root,
mode: "production",
logLevel: "warn",
build: {
ssr: true,
rollupOptions: { input: SERVER_ENTRY_ID },
},
ssr: { noExternal: true },
// React Router 8 always builds through the Vite Environment API: its SSR
// environment reads its own `build.rollupOptions.input`, not the top-level
// one, so the wrapper input is declared there too.
environments: {
ssr: {
build: { rollupOptions: { input: SERVER_ENTRY_ID } },
resolve: { noExternal: true },
},
},
plugins,
});
/**
* Build the `Framework` service implementation for a React Router v7
* project (framework mode).
*
* - `build` resolves the deploy target, then either delegates wholesale
* (`target.build`) or drives the PROJECT's own Vite install
* programmatically, mirroring what `react-router build` does: the client
* pass first (it writes the asset manifest the server pass reads), then
* the server pass with `build.ssr`. `reactRouter()` in the project's
* `vite.config.ts` owns routing, typegen, and both environments — there
* is no adapter to select and no plugin to inject beyond the fetch-handler
* entry ({@link serverEntrySource}) and the self-contained SSR bundle
* ({@link inlineServerBuildConfig}). The `BuildOutput` is read from disk:
* `serverModules` entry-first from the server directory,
* `clientDirectory` = the client directory, both observed off the
* resolved Vite config.
* - `dev` runs the project's own Vite dev server (React Router's plugin
* serves SSR, resource routes, and typegen through it with native HMR),
* scoped — closing the Scope closes the server.
*
* NOT supported: React Server Components / multi-environment builds (React
* Router's `unstable` RSC plugin). Those
* emit more than one server environment, which this two-pass build does not
* assemble; the build fails with an actionable error when no single server
* entry is produced.
*
* This module is target-agnostic: everything AWS-specific lives in
* `@alchemy.run/frontend-frameworks/react-router/aws`.
*/
export const make: (
options?: ReactRouterOptions,
) => Effect.Effect<Framework["Service"], never, FileSystem.FileSystem | Path.Path> =
Effect.fnUntraced(function* (options?: ReactRouterOptions) {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const baseRoot = options?.root ?? (yield* Effect.sync(() => process.cwd()));
const targetConfig: ReactRouterTargetConfig = {
buildDirectory: options?.buildDirectory,
};
const resolveTarget = (root: string) =>
FrameworkCore.resolveDeployTarget<ReactRouterTarget, ReactRouterTargetConfig>(
root,
options?.target ?? DEFAULT_TARGET_SPECIFIER,
targetConfig,
).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
const loadVite = (root: string) =>
FrameworkCore.loadProjectModule<ReactRouterViteModule>(root, "vite").pipe(
Effect.mapError((error) => fail("Failed to load the project's Vite install", error.cause)),
);
const removeViteManifests = (directories: ReadonlyArray<string>) =>
Effect.forEach(directories, (directory) =>
fs.remove(path.join(directory, ".vite"), { recursive: true }).pipe(Effect.ignore),
);
const build: Framework["Service"]["build"] = Effect.fn(function* (buildOptions) {
const root = buildOptions?.root ?? baseRoot;
const target = yield* resolveTarget(root);
const targetContext = {
root,
framework: "react-router",
env: buildOptions?.env,
};
// Wholesale build takeover (the AWS target uses this seam to run the
// build in a disposable child process — vite.config.* executes user
// plugins that must not touch the engine process, and React Router's
// config loader resolves `react-router.config.ts` from the cwd).
if (target.build !== undefined) {
return yield* target.build(targetContext).pipe(
Effect.mapError((error) => fail(error.message, error.cause)),
Effect.provideService(FileSystem.FileSystem, fs),
Effect.provideService(Path.Path, path),
);
}
const vite = yield* loadVite(root);
const clientCapture: OutDirCapture = {};
const serverCapture: OutDirCapture = {};
yield* Effect.tryPromise({
try: () => vite.build(inlineClientBuildConfig(root, [captureOutDirPlugin(clientCapture)])),
catch: (error) => fail("Failed to build the client", error),
});
yield* Effect.tryPromise({
try: () =>
vite.build(
inlineServerBuildConfig(root, [
serverEntryPlugin(),
captureOutDirPlugin(serverCapture),
]),
),
catch: (error) => fail("Failed to build the server", error),
});
const fallbackDir = path.resolve(root, options?.buildDirectory ?? DEFAULT_BUILD_DIRECTORY);
const clientDir =
clientCapture.outDir !== undefined
? path.resolve(root, clientCapture.outDir)
: path.join(fallbackDir, "client");
const serverDir =
serverCapture.outDir !== undefined
? path.resolve(root, serverCapture.outDir)
: path.join(fallbackDir, "server");
// `react-router build` deletes the per-environment Vite manifests once
// the server pass has consumed the client one; ours would otherwise
// ship to the CDN as a public `/.vite/manifest.json`.
yield* removeViteManifests([clientDir, serverDir]);
const output = yield* readReactRouterOutput({
dir: path.dirname(serverDir),
serverDir,
clientDir,
serverEntryFileName: target.serverEntryFileName,
}).pipe(Effect.provideService(FileSystem.FileSystem, fs));
const entryName = output.serverModules?.[0]?.name;
return yield* FrameworkCore.applyDeployTargetFinish(target, output, {
...targetContext,
...(entryName !== undefined
? { entry: path.join(output.distDirectory ?? root, entryName) }
: undefined),
}).pipe(
Effect.mapError((error) => fail(error.message, error.cause)),
Effect.provideService(FileSystem.FileSystem, fs),
Effect.provideService(Path.Path, path),
);
});
const dev: Framework["Service"]["dev"] = Effect.fn(function* (devOptions) {
const root = devOptions?.root ?? baseRoot;
const vite = yield* loadVite(root);
// `port: 0` (true OS-assigned) on Vite >= 8.2.1, probed ephemeral port
// on older Vite — see `resolveViteDevPort`.
const port = yield* FrameworkCore.resolveViteDevPort(
vite.version,
devOptions?.port ?? options?.dev?.port,
);
const host = devOptions?.host;
const server = yield* Effect.acquireRelease(
Effect.tryPromise({
try: async () => {
const server = await vite.createServer({
root,
logLevel: "warn",
server: {
port,
...(host !== undefined ? { host } : undefined),
},
});
await server.listen();
return server;
},
catch: (error) => fail("Failed to start the React Router dev server", error),
}),
(server) =>
Effect.promise(async () => {
try {
await server.close();
} catch {
// teardown is best-effort
}
}),
);
const resolved = server.resolvedUrls?.local[0];
if (resolved === undefined) {
return yield* fail("Could not determine the dev server URL");
}
// Vite reports its local URL with a trailing slash; hand back an origin
// that concatenates correctly (`${url}/about`, not `//about`).
const url = resolved.endsWith("/") ? resolved.slice(0, -1) : resolved;
// Bounded readiness probe: any HTTP response counts (vite serves
// lazily; we only need the listener to answer).
yield* Effect.tryPromise({
try: async () => {
const response = await fetch(url, { redirect: "manual" });
await response.arrayBuffer().catch(() => {});
},
catch: (error) => fail("The dev server did not become reachable", error),
}).pipe(Effect.retry({ schedule: Schedule.spaced("250 millis"), times: 40 }));
return { url };
});
return Framework.of({ build, dev });
});
/** The resolved React Router build output directories. */
export interface ReactRouterOutputDirs {
/** Root output directory (`<root>/build`) — the parent of both. */
readonly dir: string;
/** Server bundle directory (`<root>/build/server`). */
readonly serverDir: string;
/** Client assets directory (`<root>/build/client`), `public/` copied in. */
readonly clientDir: string;
/**
* The emitted server entry file name within `serverDir`.
* @default "index.js"
*/
readonly serverEntryFileName?: string | undefined;
}
/**
* Pick the server entry among the modules read off disk.
*
* The expected name wins. Otherwise, a build whose server directory holds
* exactly one top-level module (chunks live under `assets/`) is
* unambiguous — that module is the entry, which covers a project that sets
* `serverBuildFile` to something other than `index.js`.
*/
export const selectServerEntryName = (
moduleNames: ReadonlyArray<string>,
expected: string,
): string | undefined => {
if (moduleNames.includes(expected)) return expected;
const topLevel = moduleNames.filter(
(name) =>
!name.slice("server/".length).includes("/") &&
(name.endsWith(".js") || name.endsWith(".mjs")),
);
return topLevel.length === 1 ? topLevel[0] : undefined;
};
/**
* Map React Router's on-disk build tree onto the `BuildOutput` contract:
* `serverModules` entry-first from `<buildDirectory>/server` (POSIX names,
* sha256-hashed), `clientDirectory` = `<buildDirectory>/client`. The server
* bundle is built with `noExternal`, so it is self-contained (only `node:`
* builtins external) and there are no external workspace roots to watch.
*/
export const readReactRouterOutput = (
dirs: ReactRouterOutputDirs,
): Effect.Effect<FrameworkCore.BuildOutput, FrameworkError, FileSystem.FileSystem> =>
Effect.gen(function* () {
const expected = `server/${dirs.serverEntryFileName ?? DEFAULT_SERVER_BUILD_FILE}`;
const modules = yield* FrameworkCore.readServerModulesFromDisk({
directory: dirs.serverDir,
prefix: "server",
}).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
if (modules.length === 0) {
return yield* fail(`The React Router build produced no server modules in ${dirs.serverDir}`);
}
const entryName = selectServerEntryName(
modules.map((module) => module.name),
expected,
);
if (entryName === undefined) {
return yield* fail(
`The React Router build produced no "${expected}" entry in ${dirs.serverDir} — ` +
"React Server Components and multi-environment builds are not supported yet.",
);
}
return {
distDirectory: dirs.dir,
clientDirectory: dirs.clientDir,
serverModules: FrameworkCore.sortServerModules(modules, entryName),
externalWorkspaces: new Set<string>(),
} satisfies FrameworkCore.BuildOutput;
});
/**
* A `Layer` providing framework-core's `Framework` service for a React
* Router project — the fully-typed entrypoint for `e2e.config.ts` and
* alchemy's `AWS.Website.ReactRouter` composite.
*/
export const layer = (
options?: ReactRouterOptions,
): Layer.Layer<Framework, never, FileSystem.FileSystem | Path.Path> =>
Layer.effect(Framework, make(options));