@fluojs/cli 2.0.1 → 3.0.0

package/dist/new/starter-profiles.js

@@ -51,7 +51,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-bun-bun-http',
   platformPromptLabel: 'Bun native HTTP',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'bun', 'bun', 'http')
+  schema: createSchema('application', 'bun', 'bun', 'http'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/platform-deno', '@fluojs/runtime'],
@@ -67,7 +68,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-deno-deno-http',
   platformPromptLabel: 'Deno native HTTP',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'deno', 'deno', 'http')
+  schema: createSchema('application', 'deno', 'deno', 'http'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/platform-cloudflare-workers', '@fluojs/runtime'],
@@ -83,7 +85,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-cloudflare-workers-cloudflare-workers-http',
   platformPromptLabel: 'Cloudflare Workers',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'cloudflare-workers', 'cloudflare-workers', 'http')
+  schema: createSchema('application', 'cloudflare-workers', 'cloudflare-workers', 'http'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/platform-fastify', '@fluojs/runtime'],
@@ -99,7 +102,25 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-node-fastify-http',
   platformPromptLabel: 'Fastify',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'node', 'fastify', 'http')
+  schema: createSchema('application', 'node', 'fastify', 'http'),
+  starter: 'standard'
+}, {
+  dependencies: {
+    dependencies: ['@fluojs/core', '@fluojs/http', '@fluojs/platform-fastify', '@fluojs/react', '@fluojs/runtime', '@fluojs/validation', 'react', 'react-dom'],
+    devDependencies: ['@fluojs/cli', '@fluojs/testing', '@fluojs/vite', '@playwright/test', '@types/react', '@types/react-dom', 'happy-dom']
+  },
+  emitter: {
+    platform: 'fastify',
+    preset: 'standard',
+    runtime: 'node',
+    transport: 'http',
+    type: 'react-vite-ssr'
+  },
+  id: 'application-node-fastify-react-vite-ssr',
+  platformPromptLabel: 'Fastify',
+  promptLabel: 'React SSR + Vite',
+  schema: createSchema('application', 'node', 'fastify', 'http'),
+  starter: 'react-vite-ssr'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/platform-express', '@fluojs/runtime'],
@@ -115,7 +136,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-node-express-http',
   platformPromptLabel: 'Express',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'node', 'express', 'http')
+  schema: createSchema('application', 'node', 'express', 'http'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/platform-nodejs', '@fluojs/runtime'],
@@ -131,7 +153,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   id: 'application-node-nodejs-http',
   platformPromptLabel: 'Raw Node.js HTTP',
   promptLabel: 'Application (HTTP starter)',
-  schema: createSchema('application', 'node', 'nodejs', 'http')
+  schema: createSchema('application', 'node', 'nodejs', 'http'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime'],
@@ -146,7 +169,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-tcp',
   promptLabel: 'Microservice (transport-first starter)',
-  schema: createSchema('microservice', 'node', 'none', 'tcp')
+  schema: createSchema('microservice', 'node', 'none', 'tcp'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', 'ioredis'],
@@ -161,7 +185,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-redis-streams',
   promptLabel: 'Microservice (Redis Streams starter)',
-  schema: createSchema('microservice', 'node', 'none', 'redis-streams')
+  schema: createSchema('microservice', 'node', 'none', 'redis-streams'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', 'mqtt'],
@@ -176,7 +201,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-mqtt',
   promptLabel: 'Microservice (MQTT starter)',
-  schema: createSchema('microservice', 'node', 'none', 'mqtt')
+  schema: createSchema('microservice', 'node', 'none', 'mqtt'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', '@grpc/grpc-js', '@grpc/proto-loader'],
@@ -191,7 +217,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-grpc',
   promptLabel: 'Microservice (gRPC starter)',
-  schema: createSchema('microservice', 'node', 'none', 'grpc')
+  schema: createSchema('microservice', 'node', 'none', 'grpc'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', 'nats'],
@@ -206,7 +233,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-nats',
   promptLabel: 'Microservice (NATS starter)',
-  schema: createSchema('microservice', 'node', 'none', 'nats')
+  schema: createSchema('microservice', 'node', 'none', 'nats'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', 'kafkajs'],
@@ -221,7 +249,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-kafka',
   promptLabel: 'Microservice (Kafka starter)',
-  schema: createSchema('microservice', 'node', 'none', 'kafka')
+  schema: createSchema('microservice', 'node', 'none', 'kafka'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/di', '@fluojs/microservices', '@fluojs/runtime', 'amqplib'],
@@ -236,7 +265,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'microservice-node-none-rabbitmq',
   promptLabel: 'Microservice (RabbitMQ starter)',
-  schema: createSchema('microservice', 'node', 'none', 'rabbitmq')
+  schema: createSchema('microservice', 'node', 'none', 'rabbitmq'),
+  starter: 'standard'
 }, {
   dependencies: {
     dependencies: ['@fluojs/config', '@fluojs/core', '@fluojs/validation', '@fluojs/di', '@fluojs/http', '@fluojs/microservices', '@fluojs/platform-fastify', '@fluojs/runtime'],
@@ -251,7 +281,8 @@ export const STARTER_PROFILE_REGISTRY = [{
   },
   id: 'mixed-node-fastify-tcp',
   promptLabel: 'Mixed (HTTP API + microservice starter)',
-  schema: createSchema('mixed', 'node', 'fastify', 'tcp')
+  schema: createSchema('mixed', 'node', 'fastify', 'tcp'),
+  starter: 'standard'
 }];
 
 /** Supported scaffold shapes accepted by the current starter matrix. */
@@ -266,6 +297,8 @@ export const SUPPORTED_BOOTSTRAP_TRANSPORTS = ['http', ...SUPPORTED_MICROSERVICE
 export const SUPPORTED_BOOTSTRAP_TOOLING_PRESETS = ['standard'];
 /** Supported topology modes accepted by the current starter matrix. */
 export const SUPPORTED_BOOTSTRAP_TOPOLOGY_MODES = ['single-package'];
+/** Named starter variants accepted by `fluo new`. */
+export const SUPPORTED_BOOTSTRAP_STARTERS = ['standard', 'react-vite-ssr'];
 
 /** Default starter profile used for shape-less `fluo new` invocations. */
 export const DEFAULT_BOOTSTRAP_PROFILE = STARTER_PROFILE_REGISTRY.find(profile => profile.id === 'application-node-fastify-http');
@@ -279,7 +312,7 @@ export const DEFAULT_BOOTSTRAP_PROFILE = STARTER_PROFILE_REGISTRY.find(profile =
  */
 export function getStarterProfileForShape(shape, runtime) {
   if (runtime !== undefined) {
-    return STARTER_PROFILE_REGISTRY.find(profile => profile.schema.shape === shape && profile.schema.runtime === runtime) ?? DEFAULT_BOOTSTRAP_PROFILE;
+    return STARTER_PROFILE_REGISTRY.find(profile => profile.starter === 'standard' && profile.schema.shape === shape && profile.schema.runtime === runtime) ?? DEFAULT_BOOTSTRAP_PROFILE;
   }
   if (shape === 'application') {
     return DEFAULT_BOOTSTRAP_PROFILE;
@@ -300,7 +333,7 @@ export function getStarterProfileForShape(shape, runtime) {
  * @returns Application starter profiles for the selected runtime, or all application starters when omitted.
  */
 export function getApplicationStarterProfiles(runtime) {
-  return STARTER_PROFILE_REGISTRY.filter(profile => profile.schema.shape === 'application' && (runtime === undefined || profile.schema.runtime === runtime));
+  return STARTER_PROFILE_REGISTRY.filter(profile => profile.starter === 'standard' && profile.schema.shape === 'application' && (runtime === undefined || profile.schema.runtime === runtime));
 }
 
 /**
@@ -327,10 +360,11 @@ export function getDefaultBootstrapSchema() {
  * Finds the starter profile that exactly matches a resolved bootstrap schema.
  *
  * @param schema Fully resolved bootstrap schema.
+ * @param starter Named starter variant selected by the caller.
  * @returns The matching starter profile, or `undefined` when the schema is validation-only.
  */
-export function getStarterProfileFromSchema(schema) {
-  return STARTER_PROFILE_REGISTRY.find(profile => profile.schema.shape === schema.shape && profile.schema.runtime === schema.runtime && profile.schema.platform === schema.platform && profile.schema.transport === schema.transport && profile.schema.tooling === schema.tooling && profile.schema.topology.deferred === schema.topology.deferred && profile.schema.topology.mode === schema.topology.mode);
+export function getStarterProfileFromSchema(schema, starter = 'standard') {
+  return STARTER_PROFILE_REGISTRY.find(profile => profile.starter === starter && profile.schema.shape === schema.shape && profile.schema.runtime === schema.runtime && profile.schema.platform === schema.platform && profile.schema.transport === schema.transport && profile.schema.tooling === schema.tooling && profile.schema.topology.deferred === schema.topology.deferred && profile.schema.topology.mode === schema.topology.mode);
 }
 
 /**

package/dist/new/templates/react-vite-ssr/README.md.ejs

@@ -0,0 +1,74 @@
+# <%= projectName %>
+
+HTTP-first React SSR starter generated by `fluo new --starter react-vite-ssr`.
+
+Requires Node.js `>=24.0.0 <27`. Use Node 24 LTS for local development, CI, and container images. The server build targets `node24` and uses `@types/node@^24.0.0`.
+
+## First page
+
+```sh
+<%= installCommand %>
+<%= devCommand %>
+```
+
+Open `http://127.0.0.1:3000/products/sku-42?preview=true`, then edit
+`src/page.tsx`. The page component contains only page UI and hydrated interaction; the generated
+application wiring keeps the server/client render tree aligned for you.
+
+The decorated route remains explicit in `src/app.ts`:
+
+```ts
+@Router('/products')
+class ProductPageRouter {
+  @Path('/:sku')
+  @RequestDto(ProductPageRequest)
+  show(_input: ProductPageRequest): ReactElement {
+    return createElement(ProductPage);
+  }
+}
+```
+
+This handler still runs through `@fluojs/http` matching, DTO binding, validation, middleware,
+guards, interceptors, request scopes, and not-found behavior before the application renderer sees
+the returned `ReactElement`. Decorator-bearing application declarations stay in `.ts` files so the
+Vite transform handles them; JSX rendering stays in `.tsx` modules such as `src/page.tsx`.
+
+## Production verification
+
+```sh
+<%= typecheckCommand %>
+<%= testCommand %>
+<%= buildCommand %>
+<%= startCommand %>
+<%= testBrowserCommand %>
+```
+
+`<%= testBrowserCommand %>` starts the built Fastify server and verifies the first HTTP response, emitted
+assets, hydration, interaction, and full-document navigation without console warnings or errors.
+Install the Playwright Chrome browser first when your environment does not already provide it.
+
+## Application-owned wiring
+
+Read these files only when you need to change the default composition:
+
+- `src/app.ts` owns explicit HTTP routes and registers the application renderer.
+- `src/entry-server.tsx` is the application-owned `ReactPageRenderer`. It turns the already-loaded
+  Vite manifest into hydration assets and returns `ReactServerEntry` through
+  `createReactServerEntry(...)`. Replace this renderer when the application needs another document
+  or explicit asset policy.
+- `src/react-app.tsx` is the shared server/client document. It owns
+  `ReactClientRouterProvider`, the request route snapshot, and stylesheet placement.
+- `src/entry-client.tsx` hydrates that same document and reports a mismatch with the exact entry and
+  shared-composition files to compare.
+- `src/main.ts` loads `dist/client/.vite/manifest.json` through `src/load-manifest.ts`, then boots the
+  normal Fastify HTTP application. Missing or malformed build output points back to `<%= buildCommand %>` and
+  `vite.client.config.ts`.
+
+`@fluojs/react/vite` only parses the manifest value loaded by the application. It does not discover
+files, run Vite, serve assets, or move route ownership out of `@fluojs/http`. The Fastify asset
+controller is a minimal local starter boundary; production deployments should serve `dist/client`
+through their normal static-file or CDN infrastructure.
+
+`Link` remains a real anchor and `router.push(...)` performs full-document navigation through the
+server-owned route. This starter intentionally excludes RSC, Server Functions, file routing, a
+client route table, SPA document swapping, prefetch, and a data cache.

package/dist/new/templates/react-vite-ssr/playwright.config.ts.ejs

@@ -0,0 +1,26 @@
+import { defineConfig } from '@playwright/test';
+
+const BROWSER_TEST_PORT = 43_006;
+const serverCommand = process.env.FLUO_REACT_STARTER_SERVER_COMMAND === 'dev'
+  ? <%= devCommandJson %>
+  : <%= startCommandJson %>;
+
+export default defineConfig({
+  fullyParallel: false,
+  outputDir: 'node_modules/.cache/playwright-results',
+  testDir: './tests',
+  timeout: 30_000,
+  use: {
+    baseURL: `http://127.0.0.1:${BROWSER_TEST_PORT}`,
+    channel: 'chrome',
+    headless: true,
+  },
+  webServer: {
+    command: serverCommand,
+    env: { PORT: String(BROWSER_TEST_PORT) },
+    reuseExistingServer: false,
+    timeout: 30_000,
+    url: `http://127.0.0.1:${BROWSER_TEST_PORT}/assets/entry-client.js`,
+  },
+  workers: 1,
+});

package/dist/new/templates/react-vite-ssr/src/app.test.ts.ejs

@@ -0,0 +1,82 @@
+import { createTestApp } from '@fluojs/testing';
+import { describe, expect, it } from 'vitest';
+
+import { createAppModule } from './app';
+import { ReactStarterEntryError, createReactPageRenderer } from './entry-server';
+
+const VITE_MANIFEST = {
+  'src/entry-client.tsx': {
+    css: ['styles.css'],
+    file: 'entry-client.js',
+    isEntry: true,
+    src: 'src/entry-client.tsx',
+  },
+  'src/entry-server.tsx': {
+    file: 'entry-server.js',
+    isEntry: true,
+    src: 'src/entry-server.tsx',
+  },
+} as const;
+
+function readHtml(body: unknown): string {
+  if (body instanceof Uint8Array) {
+    return new TextDecoder().decode(body);
+  }
+  return typeof body === 'string' ? body : JSON.stringify(body);
+}
+
+describe('React Vite SSR starter', () => {
+  it('streams an HTTP-owned page with manifest-derived hydration assets', async () => {
+    const AppModule = createAppModule({
+      clientDirectory: new URL('../dist/client/', import.meta.url),
+      renderPage: createReactPageRenderer(VITE_MANIFEST),
+    });
+    const app = await createTestApp({ rootModule: AppModule });
+
+    try {
+      const response = await app.request('GET', '/products/sku-42').query('preview', 'true').send();
+      const html = readHtml(response.body);
+
+      expect(response.status).toBe(200);
+      expect(response.headers['Content-Type']).toBe('text/html; charset=utf-8');
+      expect(html).toContain('Catalog item sku-42');
+      expect(html).toContain('Preview mode');
+      expect(html).toContain('src="/assets/entry-client.js"');
+      expect(html).toContain('href="/assets/styles.css"');
+      expect(html).toContain('href="/products/sku-84?preview=false"');
+    } finally {
+      await app.close();
+    }
+  });
+
+  it('keeps route validation on the server DTO boundary', async () => {
+    const AppModule = createAppModule({
+      clientDirectory: new URL('../dist/client/', import.meta.url),
+      renderPage: createReactPageRenderer(VITE_MANIFEST),
+    });
+    const app = await createTestApp({ rootModule: AppModule });
+
+    try {
+      const response = await app.request('GET', '/products/x').query('preview', 'maybe').send();
+      expect(response.status).toBe(400);
+    } finally {
+      await app.close();
+    }
+  });
+
+  it('identifies the application entry files when the Vite manifest is incompatible', () => {
+    try {
+      createReactPageRenderer({});
+      throw new TypeError('Expected createReactPageRenderer(...) to reject an incompatible manifest.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ReactStarterEntryError);
+      if (error instanceof ReactStarterEntryError) {
+        expect(error.code).toBe('react-starter-entry-incompatible');
+        expect(error.message).toContain('src/entry-server.tsx');
+        expect(error.message).toContain('src/entry-client.tsx');
+        expect(error.message).toContain('vite.client.config.ts');
+        expect(error.message).toContain('generated build script');
+      }
+    }
+  });
+});

package/dist/new/templates/react-vite-ssr/src/app.ts.ejs

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+
+import { Module } from '@fluojs/core';
+import {
+  Controller,
+  FromPath,
+  FromQuery,
+  Get,
+  NotFoundException,
+  Optional,
+  RequestDto,
+  type RequestContext,
+} from '@fluojs/http';
+import {
+  Path,
+  ReactModule,
+  Router,
+  type ReactPageRenderer,
+} from '@fluojs/react';
+import { IsIn, IsString, MinLength } from '@fluojs/validation';
+import { createElement, type ReactElement } from 'react';
+
+import { ProductPage } from './page';
+
+const ASSET_FILE_PATTERN = /^[a-zA-Z0-9._-]+\.(?:css|js)$/u;
+
+export type ReactViteAppModuleOptions = {
+  readonly clientDirectory: URL;
+  readonly renderPage: ReactPageRenderer;
+};
+
+class ProductPageRequest {
+  @MinLength(3)
+  @IsString()
+  @FromPath('sku')
+  sku = '';
+
+  @IsIn(['true', 'false'])
+  @Optional()
+  @FromQuery('preview')
+  preview?: string;
+}
+
+class AssetRequest {
+  @FromPath('file')
+  file = '';
+}
+
+export function createAppModule(options: ReactViteAppModuleOptions) {
+  @Router('/products')
+  class ProductPageRouter {
+    @Path('/:sku')
+    @RequestDto(ProductPageRequest)
+    show(_input: ProductPageRequest): ReactElement {
+      return createElement(ProductPage);
+    }
+  }
+
+  @Controller('/assets')
+  class ViteAssetController {
+    @Get('/:file')
+    @RequestDto(AssetRequest)
+    async serve(input: AssetRequest, context: RequestContext): Promise<Uint8Array> {
+      if (!ASSET_FILE_PATTERN.test(input.file)) {
+        throw new NotFoundException('Vite asset not found.');
+      }
+
+      try {
+        const body = await readFile(new URL(input.file, options.clientDirectory));
+        context.response.setHeader(
+          'Content-Type',
+          input.file.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8',
+        );
+        return body;
+      } catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+          throw new NotFoundException('Vite asset not found.', { cause: error });
+        }
+        throw error;
+      }
+    }
+  }
+
+  @Module({
+    controllers: [ViteAssetController],
+    imports: [ReactModule.forRoot({ controllers: [ProductPageRouter], renderPage: options.renderPage })],
+  })
+  class AppModule {}
+
+  return AppModule;
+}

package/dist/new/templates/react-vite-ssr/src/entry-client.tsx.ejs

@@ -0,0 +1,29 @@
+import { hydrateRoot } from 'react-dom/client';
+
+import { ProductPage } from './page';
+import {
+  ReactAppDocument,
+  REACT_IDENTIFIER_PREFIX,
+  reportReactHydrationMismatch,
+} from './react-app';
+import './styles.css';
+
+const stylesheets = [...document.querySelectorAll<HTMLLinkElement>('link[data-vite-style]')]
+  .map((link) => link.getAttribute('href'))
+  .filter((href): href is string => href !== null);
+
+hydrateRoot(
+  document,
+  <ReactAppDocument
+    page={<ProductPage />}
+    route={{
+      params: { sku: document.documentElement.dataset.routeSku ?? '' },
+      url: `${window.location.pathname}${window.location.search}`,
+    }}
+    stylesheets={stylesheets}
+  />,
+  {
+    identifierPrefix: REACT_IDENTIFIER_PREFIX,
+    onRecoverableError: reportReactHydrationMismatch,
+  },
+);

package/dist/new/templates/react-vite-ssr/src/entry-server.tsx.ejs

@@ -0,0 +1,52 @@
+import {
+  createReactServerEntry,
+  type ReactPageRenderer,
+} from '@fluojs/react';
+import { createReactViteAssetManifest } from '@fluojs/react/vite';
+
+import { ReactAppDocument, REACT_IDENTIFIER_PREFIX } from './react-app';
+
+export class ReactStarterEntryError extends Error {
+  readonly code = 'react-starter-entry-incompatible' as const;
+
+  constructor(readonly diagnostics: readonly string[]) {
+    super(
+      [
+        'The React starter could not match its server and client entries.',
+        'Check src/entry-server.tsx, src/entry-client.tsx, and vite.client.config.ts, then run the generated build script again.',
+        ...diagnostics,
+      ].join('\n'),
+    );
+    this.name = 'ReactStarterEntryError';
+  }
+}
+
+export function createReactPageRenderer(manifest: unknown): ReactPageRenderer {
+  const result = createReactViteAssetManifest({
+    base: '/assets/',
+    entries: {
+      client: 'src/entry-client.tsx',
+      server: 'src/entry-server.tsx',
+    },
+    identifierPrefix: REACT_IDENTIFIER_PREFIX,
+    manifest,
+  });
+
+  if (!result.ok) {
+    throw new ReactStarterEntryError(
+      result.diagnostics.map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`),
+    );
+  }
+
+  const assets = result.manifest;
+  const renderPage: ReactPageRenderer = (page, context) => createReactServerEntry(
+    <ReactAppDocument
+      page={page}
+      route={{ params: context.request.params, url: context.request.url }}
+      stylesheets={assets.css}
+    />,
+    assets.hydrationOptions,
+  );
+
+  return renderPage;
+}

package/dist/new/templates/react-vite-ssr/src/load-manifest.test.ts.ejs

@@ -0,0 +1,55 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { ReactStarterManifestError, loadReactViteManifest } from './load-manifest';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+describe('React Vite manifest loading', () => {
+  it('identifies the build command when the client manifest is missing', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'fluo-react-manifest-missing-'));
+    temporaryDirectories.push(directory);
+
+    try {
+      await loadReactViteManifest(pathToFileURL(join(directory, 'manifest.json')));
+      throw new TypeError('Expected loadReactViteManifest(...) to reject a missing manifest.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ReactStarterManifestError);
+      if (error instanceof ReactStarterManifestError) {
+        expect(error.code).toBe('react-starter-manifest-missing');
+        expect(error.message).toContain('generated build script');
+        expect(error.message).toContain('generated start script');
+        expect(error.message).toContain('vite.client.config.ts');
+      }
+    }
+  });
+
+  it('identifies generated build output when the client manifest is malformed', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'fluo-react-manifest-malformed-'));
+    temporaryDirectories.push(directory);
+    const manifestPath = join(directory, 'manifest.json');
+    await writeFile(manifestPath, '{');
+
+    try {
+      await loadReactViteManifest(pathToFileURL(manifestPath));
+      throw new TypeError('Expected loadReactViteManifest(...) to reject malformed JSON.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ReactStarterManifestError);
+      if (error instanceof ReactStarterManifestError) {
+        expect(error.code).toBe('react-starter-manifest-malformed');
+        expect(error.message).toContain('dist/client/.vite/manifest.json');
+        expect(error.message).toContain('generated build script');
+      }
+    }
+  });
+});

package/dist/new/templates/react-vite-ssr/src/load-manifest.ts.ejs

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises';
+
+export type ReactStarterManifestErrorCode =
+  | 'react-starter-manifest-malformed'
+  | 'react-starter-manifest-missing'
+  | 'react-starter-manifest-read-failed';
+
+export class ReactStarterManifestError extends Error {
+  constructor(
+    readonly code: ReactStarterManifestErrorCode,
+    message: string,
+    options: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'ReactStarterManifestError';
+  }
+}
+
+export async function loadReactViteManifest(manifestUrl: URL): Promise<unknown> {
+  let source: string;
+
+  try {
+    source = await readFile(manifestUrl, 'utf8');
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      throw new ReactStarterManifestError(
+        'react-starter-manifest-missing',
+        'The Vite client manifest is missing. Run the generated build script before the generated start script; if it remains missing, check build.manifest and build.outDir in vite.client.config.ts.',
+        { cause: error },
+      );
+    }
+
+    throw new ReactStarterManifestError(
+      'react-starter-manifest-read-failed',
+      'The Vite client manifest could not be read. Check the generated dist/client directory and file permissions, then run the generated build script again.',
+      { cause: error },
+    );
+  }
+
+  try {
+    const manifest: unknown = JSON.parse(source);
+    return manifest;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new ReactStarterManifestError(
+        'react-starter-manifest-malformed',
+        'The Vite client manifest is not valid JSON. Remove dist, run the generated build script again, and do not edit dist/client/.vite/manifest.json by hand.',
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}