Vite SSR BOOST

Quick start

Add to an existing app:

npm i @lomray/vite-ssr-boost
npx ssr-boost init --dry-run
npx ssr-boost init --apply
npm install
npx ssr-boost doctor

@lomray/vite-ssr-boost adds server rendering to your Vite project while keeping your route objects and components. Build SSR and SPA output from the same app, and choose a managed Express server or a Fetch handler for your own transport.

The migration guide walks through the five-file change:

| File | Change | | ---------------- | ---------------------------------------------------- | | vite.config.ts | Add SsrBoost() to the plugins. | | src/index.html | Add the SSR outlet inside the root element. | | src/client.ts | Use the browser entry for hydration or SPA mounting. | | src/server.ts | Add the server entry and request-scoped setup. | | package.json | Use the ssr-boost dev, build and start commands. |

Start a new app with the minimal template (default):

npm create @lomray/ssr-app@latest my-app

Choose the full template by passing the flag after --:

npm create @lomray/ssr-app@latest my-app -- --template full

Starting a new app? Choose one of the template branches with the npm create command or clone the branch directly.

To defer loader work, return { title, slow: fetchUsers() } and render slow with Suspense and <Await>; see the streaming guide.

Who this is for

• Teams adding SSR to a Vite SPA with React Router route objects.
• Teams that need server rendering and SPA output from one application.
• Teams that want to control request hooks, response headers and deployment.

What you keep

• Your Vite configuration and plugins, with the SSR plugin added.
• Your React Router route objects.
• Your components, after removing browser globals from server execution.
• Your React version within the package's peer range: React and React DOM >=18.2.0.
• Your hosting choice, provided it can run the selected SSR transport or serve SPA files.

Loader and action promises support <Await> and React 19 use() during hydration by default. Stream loader data shows the loader pattern and hydration: 'early' for shell interaction before slow boundaries finish.

What you add

Add SsrBoost() to the Vite plugins, wire client.ts and server.ts, and replace the Vite scripts with ssr-boost commands. The migration guide includes these entries and the HTML outlet, copied from the minimal example.

Deferred router data needs no additional state library. Keep footer hydration by default, or opt into early hydration with custom state available at onShellReady.

Choose your server

Managed CLI (default). Use ssr-boost dev for Express with Vite development and HMR, then ssr-boost build and ssr-boost start for production assets and SSR. The server entry is @lomray/vite-ssr-boost/adapters/express/entry, with hooks for requests, rendering and responses.

Fetch handler. Import createHandler from @lomray/vite-ssr-boost/core/handler and connect it through adapters/node, adapters/express, adapters/fastify, adapters/hono or adapters/edge. Your transport owns the development server, static assets and route-asset injection; follow Runtime adapters when you need this control.

Both paths are measured weekly in the public ssr-benchmarks repository: the same application on vite-ssr-boost, React Router Framework mode, Vike, TanStack Start and Next.js, and a runtime matrix that serves the boost build through Express, node:http, Fastify, Hono and Bun. See Benchmarks for what is measured and how to reproduce it.

Not a fit when

• You need an implementation of React Server Components and Server Actions.
• You want the package to impose file-system routing conventions.
• You want zero server ownership for SSR.

Install and template quick start

See Compatibility for the package Node requirement. The example uses Node 22.23.2; React Router and build tools can raise the required Node version.

Start with the minimal template:

npm create @lomray/ssr-app@latest my-app
cd my-app
npm run develop

Or clone the template branch directly:

git clone --branch example/minimal https://github.com/Lomray-Software/vite-template.git
cd vite-template
npm ci
npm run develop

Its six direct runtime dependencies are React, React DOM, React Router, vite-ssr-boost, @lomray/react-head-manager and isbot.

For production, run npm run build and npm run start:ssr. For a SPA build, run npm run build:spa and npm run start:spa. See Example projects for the prod template with state management and deployment workflows.

Already running this in production? Point our free performance audit at the URL. It reports Core Web Vitals, JavaScript bundle weight and whether the HTML really arrives server-rendered. No signup.

Compatibility

See the support policy for version lifetimes, response targets and breaking-change commitments, and Upgrade from 7 to 8 for migration instructions.

The package is tested against the current and previous major of React, React Router and Vite, with an additional Vite 6 row. The compatibility workflow runs the full test suite and a built Worker check on Node 22.23.2 with these exact combinations:

| React / React DOM | React Router | Vite | | ----------------- | ------------ | ------- | | 18.2.0 | 7.18.3 | 6.4.3 | | 19.2.8 | 7.18.3 | 7.3.6 | | 19.2.8 | 8.3.1 | 8.2.2 |

package.json declares Node >=22.12.0 and these peer ranges:

| Peer | Range | | -------------- | ---------- | | react | >=18.2.0 | | react-dom | >=18.2.0 | | react-router | >=7.0.1 | | vite | >=5 |

Peer ranges allow installation; the matrix tests only the combinations above. It does not test every version in those ranges or every combination of majors.

Examples

The example projects guide explains the wiring in each template branch.

| Template branch | What it includes | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | prod | MobX state management, component-level data streaming, metadata and deployment workflows. | | example/minimal | Six runtime dependencies, loaders, a lazy route with CSS, redirects, 404s, metadata and a browser-only route. | | example/custom-server | Managed CLI development and an application-owned Fastify 5 production server with static assets, compression, route assets and Early Hints. | | example/localization | Per-request i18next, cookie and header language selection, and language state restored before hydration. |

Documentation

Test SSR routes without a server with @lomray/vite-ssr-boost/testing; see the Vitest and Playwright guide.

• Documentation site, comparison guide and FAQ.
• Hydration order and streaming and Benchmarks.
• API: Plugin, Browser entry, Server entry, Node production, Components and helpers and CLI.

AI agents

The repository includes ssr-boost-migrate and ssr-boost-new-app in the Agent Skills format.

Claude Code plugin:

claude plugin marketplace add Lomray-Software/vite-ssr-boost
claude plugin install ssr-boost@lomray

Codex CLI, from this checkout:

mkdir -p ~/.codex/skills
cp -R skills/ssr-boost-migrate skills/ssr-boost-new-app ~/.codex/skills/
# Or use the target application's .codex/skills directory.

Current Codex versions document .agents/skills for discovery; use that destination or the symlinks in AI usage and installation. That page also covers local Claude plugin testing before the files reach the default branch.

For Cursor, copy the folders into the app's skills/ directory and add a .cursor/rules/ssr-boost.mdc rule pointing to the relevant SKILL.md; see the complete rule. Other agents can use llms.txt or llms-full.txt.

License

Made with 💚

Published under MIT License.