Ssr Boost New App

Create an SSR Boost application

Work in the user's chosen parent directory and follow its repository instructions. Use the published scaffolder and inspect the resulting files; template branches evolve independently of this skill. The reference APIs target vite-ssr-boost 8.x. Links to upstream docs remain usable when this folder is installed alone.

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. Choose and scaffold

Check Node and the current template catalog:

node --version
npm view @lomray/create-ssr-app version engines
npm create @lomray/ssr-app@latest -- --help

SSR Boost requires Node >=22.12.0; satisfy the template dependencies' engines too (the template tooling uses Node 22.23.2). The published create-ssr-app catalog has these five choices:

Use minimal unless the requested app benefits from another template. Those commands prompt for a directory on a TTY; non-TTY defaults to my-ssr-app. Put npm flags after --. To choose a directory explicitly, suppress prompts and leave Git initialization to the user/repository workflow:

npm create @lomray/ssr-app@latest my-app -- --template minimal --no-git --yes
cd my-app

Use --no-install when you need to inspect dependencies before installing. The normal command installs them already. --no-git also removes Husky and scripts.prepare; the generated CI workflow is still included. Do not use --force to scaffold over an existing application.

2. Inspect the structure and establish checks

Read package.json, the lockfile, .nvmrc, Vite config, .env examples, src/app.tsx, src/client.ts, src/server.ts, src/routes/index.ts, src/pages/, scripts/ and .github/workflows/ci.yml. These templates use Vite root: 'src', public assets outside it, and build/client plus build/server output. Keep the actual aliases and filenames. Review entries for the wrapper prop contract and exact managed/Fetch API shapes.

npx ssr-boost doctor --json
npm run develop

Review all doctor errors and version warnings; repeat until errors are fixed. Current templates also use the tested React 19 / Router 8 / Vite 8 combination. For Vite 6/7, React 18/19 and Router 7 compatibility choices, use the tested matrix, not just peer ranges. Keep matching React/React DOM versions and one physical copy of each.

Inspect the homepage, direct nested routes and a lazy route during development, then stop the owned server. Keep the generated size:check budget as the starting baseline and the smoke script with its route expectations; update expectations when replacing sample pages. There is no package CLI smoke subcommand.

3. Implement the requested application

• Add static Data mode route objects, stable IDs, layouts, error boundaries and literal lazy imports using routes, loaders and actions. There is no automatic file-system router, RSC or Server Actions layer. Data mode loaders/actions also run in the browser on navigation; use APIs for secrets, database calls and Worker bindings.
• Return an object with a slow promise and consume it in Suspense/Await; use React 19 use() only inside a boundary. Forward request.signal to I/O. Test success, rejection, redirect and 404 paths. See streaming.
• Preserve @lomray/react-head-manager: create a Manager per request, provide it through App, inject tags at shell readiness and transfer its JSON state to client init. Add route titles/descriptions with <Meta>. Entry shapes show every import and hook.
• For localization, use the localization template's per-request i18next instance. Choose language from the request cookie, then Accept-Language, then an app default; transfer chosen language/resources and initialize the client before hydration. Do not reuse a mutable server i18next instance across requests or choose a different browser language for the initial render. See the localization example.
• Keep public config in import.meta.env.VITE_*; these values are embedded into browser code. Keep secrets in server runtime variables or platform secrets, never in VITE_*, route data, getState, HTML or tracked env files. Follow the configured Vite envDir, add a safe .env.example, and restart development after env changes. Worker bindings stay in server-only modules. See environment guidance.
• Restore state only inside the browser entry's async init. Default footer hydration is suitable unless early interaction is requested. Early mode requires hydration: 'early', an async client script, and custom state ready at onShellReady. Keep browser globals in effects or client-only routes.