Ssr Boost Migrate

Migrate a Vite SPA

Use this procedure in the application repository. Read its instructions and preserve its package manager, providers, routes and unrelated changes. The API examples target vite-ssr-boost 8.x; read the installed version before changing imports. Documentation links point to the upstream repository so they work when this skill is copied on its own.

The testing kit, incremental SSR policy and Worker helper require a release containing those APIs; the stable 8.3.0 template dependency predates them. For a prerelease evaluation, the published 8.4.0-beta.4 was used for these workflows. Check installed exports and the project's release policy before adopting a prerelease; do not silently use one for a stable-only production rollout.

1. Establish the baseline

• Inspect package.json, the lockfile, Vite config, HTML module script, browser entry, route definitions and deployment target. Run existing checks and record the current client JavaScript size before editing.
• The migration baseline is Vite 6/7, matching React/React DOM 18/19, and react-router 7 Data mode. Tested combinations include React 18.2.0 + Router 7.18.3 + Vite 6.4.3 and React 19.2.8 + Router 7.18.3 + Vite 7.3.6. Node must satisfy the installed packages' engines (SSR Boost requires >=22.12.0). See compatibility. Newer templates also use the separately tested React 19 / Router 8 / Vite 8 row; peer ranges alone are not proof of compatibility.
• If the SPA uses JSX BrowserRouter/Routes, first migrate it to one createBrowserRouter(routes) and RouterProvider. Preserve nested layouts, error boundaries and provider order. Route and loader shapes include a minimal before entry. Verify the SPA still works before adding SSR. Do not move to React Router Framework mode.
• Record browser-only imports, module-scope state reads, custom router options, multiple roots and non-root Vite base. Automatic init deliberately refuses ambiguous startup code; preserve it with the manual entry shapes and migration guide.

2. Preview, review, apply

Run from the application root:

npx @lomray/vite-ssr-boost init --dry-run

With no flag, init also defaults to a dry run. Review the complete diff: existing Vite plugins remain, exactly one outlet is inside #root, client and server share routes and the same wrapper tree, and scripts/dependencies are correct. Then apply the reviewed plan:

npx @lomray/vite-ssr-boost init --apply
npm install
npx ssr-boost doctor --json

Init does not install packages. It preserves the original browser filename (often src/main.tsx), creates src/server.ts, and sets clientFile/serverFile relative to the Vite root. It can extract inline routes into routes.ssr.tsx. Do not rename files just to match examples. Review the changed build script: init replaces tsc -b && vite build, so retain type checking as a separate ts:check script. A second apply should report no changes.

For explicit paths use --root <project> --entry <browser-file> --routes <exported-route-module>; the file overrides are relative to the project, not the Vite root. If analysis fails, use the reported file/line and the manual guide; do not repeatedly apply or delete custom code to force acceptance.

3. Complete request state and data loading

Read entries and createHandler options before editing either entry. Use browser/entry and adapters/express/entry; node/entry was removed in v8. Keep the managed CLI unless the chosen target requires an application-owned transport.

Move getServerState reads and store construction into the browser entry's async init, after SSR state is ready. Use isSSRMode for the SPA fallback. Create server stores and head managers per request in onRequest; return JSON snapshots from getState. Keep browser globals in effects or client-only boundaries, and preserve equivalent first-render data on both sides.

Use streamed loader/action shapes: return an object with a slow promise, then consume it with Suspense and <Await> (or React 19 use). Keep Data mode loaders/actions browser-compatible for navigation; server-only I/O belongs behind an API. Forward request.signal. Keep footer hydration unless early shell interaction is required; early mode needs an async module script and all custom state at shell readiness. See streaming.