Cut SSR memory: ssr/client page convention, smaller pool, heap cap

Each Inertia SSR Node worker loads the entire server bundle into its own
V8 heap, including authenticated, interactive pages that don't benefit
from server rendering — wasteful on small instances. Three levers:

- Split pages into pages/ssr/ (server-rendered: public/SEO) and
  pages/client/ (client-only: authed/interactive). The strategy dir is
  stripped from the Inertia page name, so controllers are unchanged. The
  generator now emits _pages.ts (lazy client manifest, code-splitting
  preserved) + _ssr_pages.ts (ssr-only, plus a client-only set that
  ssr.tsx renders as a server-side no-op).
- SSR_POOL_SIZE env (default 2) sizes the Node worker pool.
- NODE_OPTIONS=--max-old-space-size=160 in the Dockerfile caps each
  worker's V8 heap.

Generate the registries before esbuild in assets.build/deploy (the
client bundle imports _pages.ts). Exclude the generated registries from
the biome formatter. Document the split in docs/frontend-pages.md,
CLAUDE.md, and the README.

Author: andreogle

.gitignore

@@ -56,8 +56,9 @@ npm-debug.log
 # TypeScript incremental build info (e.g. from `tsc -p tsconfig.e2e.json`)
 *.tsbuildinfo
 
-# Auto-generated SSR pages registry
+# Auto-generated page registries
 /assets/js/_ssr_pages.ts
+/assets/js/_pages.ts
 
 # LSP
 .elixir_ls

CLAUDE.md

@@ -27,12 +27,12 @@ These are the rules that must not be forgotten or looked up — they're the ones
 
 **Inertia (this project's frontend)**
 - Use `render_inertia/2|3`, never `render/3`, for Inertia pages. Don't use LiveView for Inertia pages
-- Page components are **always** `.tsx` (TypeScript), in `assets/js/pages/`
+- Page components are **always** `.tsx` (TypeScript), under `assets/js/pages/` in one of two strategy dirs: **`pages/ssr/`** (server-rendered: public / SEO / first-paint pages) or **`pages/client/`** (client-only: authenticated, interactive, heavy pages — kept out of the Node SSR bundle). The strategy dir is stripped from the Inertia page name, so `render_inertia("Dashboard")` maps to `pages/client/Dashboard.tsx`. The `_pages.ts` / `_ssr_pages.ts` registries are auto-generated from these dirs by `build/generate-ssr-pages.js` — never edit them by hand. New public page → `ssr/`; new authed page → `client/`
 - Layout components live in `assets/js/layouts/` (e.g. `AppLayout`, `AuthLayout`)
 - Reusable UI primitives live flat in `assets/js/components/` (`Button`, `Spinner`, `Select`, `DropdownMenu`, `AlertDialog`, …) — no sub-folders
 - Forms use Inertia's `useForm` hook; errors come from `assign_errors(conn, changeset)` on the server
 - **No raw `try/catch` for async work — wrap every Promise in `go()` from `@api3/promise-utils`** (sync work uses `goSync`). It returns `{ success, data, error }`, which forces every call site to acknowledge the failure path explicitly and prevents the "swallow the error and move on" pattern that hides real bugs. The same applies to dynamic `import()`, `fetch()`, JSON parsing, and any vendor SDK call. The only acceptable exception is at top-level error boundaries that genuinely *do* need to catch everything synchronously
-- Never edit `assets/js/_ssr_pages.ts` — it's auto-generated
+- Never edit `assets/js/_pages.ts` or `assets/js/_ssr_pages.ts` — they're auto-generated
 - **Validation errors must redirect, not re-render.** On `{:error, changeset}` always use `conn |> assign_errors(changeset) |> redirect(to: ~p"/current-page")`. Do **not** use `put_status(:unprocessable_entity) |> render_inertia(...)` — Inertia updates the browser URL to the POST/PUT target when you re-render, which is both wrong UX and a regression risk. The Inertia plug flashes errors through the session across the redirect, so the form still shows them
 - Use the `~p"/..."` sigil (verified routes) for every internal URL — in controllers, tests, and anywhere else in Elixir. Never write raw route strings; compile-time verification catches typos and broken links
 - **JSON serialisation goes through `*_json.ex` view modules**, never ad-hoc serializer modules (no `*Props`, `*Serializer`, or per-controller helpers). One module per resource at `lib/elixir_react_starter_web/controllers/<resource>_json.ex` (e.g. `ElixirReactStarterWeb.PostJSON`) exposes `index/1` and `show/1` (the Phoenix 1.8 equivalents of `render_many`/`render_one`) that both delegate to a single `data/2`. Inertia callers use `MyJSON.data(record, viewer)` directly inside `assign_prop`; JSON API endpoints use `index`/`show` via `render`. This keeps the wire shape for a resource in one place so multiple callers can't drift

Dockerfile

@@ -109,6 +109,11 @@ ENV MIX_ENV="prod"
 # `bin/server` (from rel/overlays) sets PHX_SERVER=true and boots the
 # endpoint. PORT is read in runtime.exs; default matches EXPOSE.
 ENV PORT=4000
+# Cap each Inertia SSR Node worker's V8 heap. The BEAM spawns these node
+# processes (and the HEALTHCHECK below) and they inherit NODE_OPTIONS, so
+# this bounds the Node side of memory alongside SSR_POOL_SIZE. Override in
+# the deploy env if a heavier SSR page needs more headroom.
+ENV NODE_OPTIONS="--max-old-space-size=160"
 EXPOSE 4000
 
 COPY --from=builder --chown=app:app /app/_build/prod/rel/elixir_react_starter ./

README.md

@@ -95,7 +95,8 @@ mix docs
 
 In development they're also served at
 [`/dev/docs`](http://localhost:4000/dev/docs/index.html). Topic guides live in
-`docs/` — e.g. the [End-to-End Testing guide](docs/e2e-testing.md).
+`docs/` — e.g. the [End-to-End Testing guide](docs/e2e-testing.md) and
+[Frontend Pages: SSR vs. Client](docs/frontend-pages.md).
 
 ## Deployment
 
@@ -118,8 +119,12 @@ docker run -p 4000:4000 \
 `config/runtime.exs` requires `DATABASE_URL`, `MAILJET_API_KEY`, `MAILJET_SECRET`,
 and `SECRET_KEY_BASE` and will refuse to boot without them. `PHX_HOST` defaults to
 `example.com` but should always be set in production (it's used for absolute URLs
-in emails). `PORT` (default `4000`), `POOL_SIZE`, `ECTO_IPV6`, and
-`DNS_CLUSTER_QUERY` are optional.
+in emails). `PORT` (default `4000`), `POOL_SIZE`, `ECTO_IPV6`,
+`DNS_CLUSTER_QUERY`, `SSR_POOL_SIZE` (number of Inertia SSR Node workers,
+default `2`), and `NODE_OPTIONS` (set in the Dockerfile to
+`--max-old-space-size=160`, caps each SSR worker's V8 heap) are optional. The
+last two are the main levers on the Node-side memory the SSR pool uses — see
+[Frontend Pages: SSR vs. Client](docs/frontend-pages.md).
 
 Database migrations run via the release: `bin/migrate`. See Phoenix's
 [deployment guides](https://hexdocs.pm/phoenix/deployment.html) for hosting specifics.

assets/biome.json

@@ -12,7 +12,9 @@
       "!**/pnpm-lock.yaml",
       "!**/.docusaurus/**",
       "!**/build/",
-      "!**/server/static/**"
+      "!**/server/static/**",
+      "!js/_pages.ts",
+      "!js/_ssr_pages.ts"
     ],
     "indentStyle": "space",
     "indentWidth": 2,

assets/build/generate-ssr-pages.js

@@ -1,12 +1,24 @@
-// Scans assets/js/pages/ and generates _ssr_pages.ts with static imports.
-// This is required because the SSR esbuild bundle uses --format=cjs which
-// doesn't support --splitting or dynamic imports.
+// Scans assets/js/pages/{ssr,client}/ and generates two page registries:
+//
+//   * _pages.ts      — client manifest: EVERY page as a lazy `() => import()`
+//                      loader, keyed by Inertia page name. Lazy so esbuild
+//                      code-splits one chunk per page. Used by app.tsx.
+//   * _ssr_pages.ts  — SSR manifest: static imports for `ssr/` pages only,
+//                      plus the set of client-only page names. Used by
+//                      ssr.tsx, whose CJS bundle can't do dynamic import.
+//
+// The strategy directory (`ssr/` or `client/`) decides whether a page is
+// server-rendered; it is stripped from the page name, so controllers keep
+// calling `render_inertia("Dashboard")` regardless of where the file lives.
 
 const fs = require('node:fs');
 const path = require('node:path');
 
 const PAGES_DIR = path.join(__dirname, '..', 'js', 'pages');
-const OUTPUT = path.join(__dirname, '..', 'js', '_ssr_pages.ts');
+const CLIENT_OUTPUT = path.join(__dirname, '..', 'js', '_pages.ts');
+const SSR_OUTPUT = path.join(__dirname, '..', 'js', '_ssr_pages.ts');
+
+const STRATEGIES = ['ssr', 'client'];
 
 function findPages(dir, base = '') {
   if (!fs.existsSync(dir)) return [];
@@ -24,50 +36,91 @@ function findPages(dir, base = '') {
     }
   }
 
-  return pages.sort();
+  return pages;
+}
+
+// Collect every page across both strategy directories.
+const all = [];
+for (const strategy of STRATEGIES) {
+  for (const rel of findPages(path.join(PAGES_DIR, strategy))) {
+    all.push({
+      strategy,
+      name: rel.replace(/\.tsx$/, ''),
+      importPath: `./pages/${strategy}/${rel}`,
+    });
+  }
+}
+
+// Only quote keys that aren't valid JS identifiers (e.g. contain '/').
+const keyFor = (name) => (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `'${name}'`);
+
+function writeIfChanged(file, content, label) {
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (existing !== content) {
+    fs.writeFileSync(file, content);
+    console.log(label);
+  }
 }
 
-const pages = findPages(PAGES_DIR);
+// --- client manifest (_pages.ts) ----------------------------------------
+const clientEntries = [...all]
+  .sort((a, b) => a.name.localeCompare(b.name))
+  .map((p) => `  ${keyFor(p.name)}: () => import('${p.importPath}'),`)
+  .join('\n');
+
+const clientContent = `// Auto-generated by build/generate-ssr-pages.js — do not edit manually
 
-// Sort by full import path matching Biome's organizeImports order.
-// Biome sorts './pages/Settings/X' before './pages/Settings.tsx',
-// so we replace '.' in extensions with a high-sorting char for comparison.
-const sortedByImportPath = pages
-  .map((p) => ({ page: p, importPath: `./pages/${p}` }))
+// Lazy client page loaders keyed by Inertia page name (the ssr/ or client/
+// strategy directory is stripped). Lazy import() so esbuild code-splits one
+// chunk per page.
+// biome-ignore lint/suspicious/noExplicitAny: Inertia supplies props at render time, not via a React parent.
+const pages: Record<string, () => Promise<{ default: React.ComponentType<any> }>> = {
+${clientEntries}
+};
+
+export default pages;
+`;
+
+// --- SSR manifest (_ssr_pages.ts) ---------------------------------------
+// Sort static imports by full import path to match Biome's import order
+// (Biome sorts './pages/Settings/X' before './pages/Settings.tsx', so swap
+// the extension for a high-sorting char when comparing).
+const ssrSorted = all
+  .filter((p) => p.strategy === 'ssr')
   .sort((a, b) => {
     const keyA = a.importPath.replace(/\.tsx$/, '\uffff');
     const keyB = b.importPath.replace(/\.tsx$/, '\uffff');
     return keyA.localeCompare(keyB);
   });
 
-const imports = sortedByImportPath.map((item, i) => `import Page${i} from '${item.importPath}';`).join('\n');
+const ssrImports = ssrSorted.map((p, i) => `import Page${i} from '${p.importPath}';`).join('\n');
+const ssrEntries = ssrSorted.map((p, i) => `  ${keyFor(p.name)}: Page${i},`).join('\n');
 
-const entries = sortedByImportPath
-  .map((item, i) => {
-    const key = item.page.replace(/\.tsx$/, '');
-    // Only quote keys that aren't valid JS identifiers (e.g. contain '/')
-    const formattedKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `'${key}'`;
-    return `  ${formattedKey}: Page${i},`;
-  })
-  .join('\n');
+const clientOnly = all
+  .filter((p) => p.strategy === 'client')
+  .map((p) => p.name)
+  .sort();
+
+const clientOnlySet = clientOnly.length
+  ? `new Set<string>([\n${clientOnly.map((n) => `  '${n}',`).join('\n')}\n])`
+  : 'new Set<string>()';
 
-const content = `// Auto-generated by build/generate-ssr-pages.js — do not edit manually
-${imports}
+const ssrContent = `// Auto-generated by build/generate-ssr-pages.js — do not edit manually
+${ssrImports}
 
-// Inertia injects props from the page protocol at render time, so components
-// in this map don't have props supplied by a React parent. ComponentType<any>
-// reflects that contract — pages with required props still type-check.
-// biome-ignore lint/suspicious/noExplicitAny: see comment above
+// Server-rendered pages (those under pages/ssr/), keyed by Inertia page name.
+// biome-ignore lint/suspicious/noExplicitAny: Inertia supplies props at render time, not via a React parent.
 const pages: Record<string, React.ComponentType<any>> = {
-${entries}
+${ssrEntries}
 };
 
+// Pages that exist but are intentionally client-only (pages/client/). ssr.tsx
+// renders these as a server-side no-op so the client takes over, instead of
+// failing — while a genuinely unknown name still throws.
+export const ssrClientOnly = ${clientOnlySet};
+
 export default pages;
 `;
 
-const existing = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, 'utf8') : '';
-
-if (existing !== content) {
-  fs.writeFileSync(OUTPUT, content);
-  console.log(`SSR pages registry updated (${pages.length} pages)`);
-}
+writeIfChanged(CLIENT_OUTPUT, clientContent, `Client pages registry updated (${all.length} pages)`);
+writeIfChanged(SSR_OUTPUT, ssrContent, `SSR pages registry updated (${ssrSorted.length} pages)`);

assets/js/app.tsx

@@ -3,6 +3,7 @@ import { go } from '@api3/promise-utils';
 import { createInertiaApp, router } from '@inertiajs/react';
 import { createElement, StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import pages from './_pages';
 import { AppProviders } from './app-providers';
 import ErrorBoundary from './components/ErrorBoundary';
 import { syncLocale } from './components/LocaleSync';
@@ -23,12 +24,19 @@ function applyFlash(flash?: Flash) {
 
 createInertiaApp({
   resolve: async (name) => {
-    const result = await go(() => import(`./pages/${name}.tsx`));
+    const loader = pages[name];
+    if (!loader) {
+      const error = new Error(`Page not found: ${name}`);
+      console.error(error);
+      throw error;
+    }
+
+    const result = await go(loader);
     if (!result.success) {
       console.error(`Failed to load page "${name}":`, result.error);
       throw result.error;
     }
-    return result.data;
+    return result.data.default;
   },
   setup({ App, el, props }) {
     syncLocale(props.initialPage.props);

assets/js/pages/Dashboard.tsx assets/js/pages/client/Dashboard.tsxassets/js/pages/Dashboard.tsx renamed to assets/js/pages/client/Dashboard.tsx

@@ -1,7 +1,7 @@
 import { usePage } from '@inertiajs/react';
 import { useTranslation } from 'react-i18next';
-import AppLayout from '../layouts/AppLayout';
-import type { CurrentUser } from '../types';
+import AppLayout from '../../layouts/AppLayout';
+import type { CurrentUser } from '../../types';
 
 export default function Dashboard() {
   const { current_user } = usePage<{ current_user: CurrentUser }>().props;

assets/js/pages/Settings.tsx assets/js/pages/client/Settings.tsxassets/js/pages/Settings.tsx renamed to assets/js/pages/client/Settings.tsx

@@ -9,10 +9,10 @@ import {
   AlertDialogFooter,
   AlertDialogTitle,
   AlertDialogTrigger,
-} from '../components/AlertDialog';
-import Button from '../components/Button';
-import { inputClass } from '../components/ui';
-import AppLayout from '../layouts/AppLayout';
+} from '../../components/AlertDialog';
+import Button from '../../components/Button';
+import { inputClass } from '../../components/ui';
+import AppLayout from '../../layouts/AppLayout';
 
 export default function Settings() {
   const { t } = useTranslation();

assets/js/pages/Auth/ForgotPassword.tsx …ets/js/pages/ssr/Auth/ForgotPassword.tsxassets/js/pages/Auth/ForgotPassword.tsx renamed to assets/js/pages/ssr/Auth/ForgotPassword.tsx assets/js/pages/Auth/ForgotPassword.tsx renamed to assets/js/pages/ssr/Auth/ForgotPassword.tsx

@@ -1,9 +1,9 @@
 import { useForm } from '@inertiajs/react';
 import { useTranslation } from 'react-i18next';
-import Button from '../../components/Button';
-import Link from '../../components/Link';
-import { inputClass } from '../../components/ui';
-import AuthLayout from '../../layouts/AuthLayout';
+import Button from '../../../components/Button';
+import Link from '../../../components/Link';
+import { inputClass } from '../../../components/ui';
+import AuthLayout from '../../../layouts/AuthLayout';
 
 export default function ForgotPassword() {
   const { t } = useTranslation();