npm - @zerotal/inertia - Versions diffs - 1.13.3 → 1.13.5 - Mend

@zerotal/inertia 1.13.3 → 1.13.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -8,6 +8,31 @@ follows the Zerotal monorepo's unified versioning.
 ## [Unreleased]
+## [1.13.5] — 2026-09-01
+### Fixed
+- **`inertia.ssr: true` now actually server-renders.** The flag registered `POST /__ssr`
+  and nothing in the request path consulted it, so an app that set it — and read the
+  documentation, which said the server renders the component into the template — got
+  exactly the empty root it had before.
+  `Inertia.render()` renders the component into the root, injects the page's `<Head>` into
+  the served `<head>`, and marks the root `data-server-rendered`. The scaffolded `app.tsx`
+  already hydrated on that attribute, so the client half needed no change: an app turns SSR
+  on with one config line and nothing else.
+  Server rendering was previously reachable only by rewriting each route to
+  `Inertia.stream()`, one call site at a time, which is not what a global switch means. An
+  app that did that can go back to `render()`.
+  A component that fails to render falls back to the client-rendered document with a
+  warning rather than failing the route: the page still works in a browser, and taking a
+  route down because an _optimisation_ failed would make `ssr: true` a liability.
+  `POST /__ssr` is unchanged and stays documented for what it is — the contract for an
+  external renderer, not the in-process switch.
 ## [1.13.2] — 2026-08-31
 ### Fixed

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.13.3",
+  "version": "1.13.5",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -34,7 +34,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.13.3"
+    "@zerotal/core": "1.13.5"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/inertia.ts CHANGED Viewed

@@ -439,6 +439,47 @@ function _writeInertiaJson(ctx: HttpContext, pageObject: unknown): void {
   });
 }
+/** Whether `inertia.ssr` is on. Read per request, so a config change needs no rebuild. */
+function _ssrEnabled(): boolean {
+  return config.safe<boolean>("inertia.ssr", false) === true;
+}
+/**
+ * The full document with the component rendered into the root.
+ *
+ * Buffered rather than streamed, because this is `render()`: the caller asked for a
+ * page, not for time-to-first-byte. {@link inertiaStream} is the streaming form and
+ * stays a per-route choice, since streaming trades TTFB against a shell that arrives
+ * in pieces — a decision that belongs to a route rather than to an application.
+ *
+ * Falls back to the un-rendered document when a component cannot be rendered. A page
+ * that fails to server-render still works in the browser, so taking the route down
+ * because an *optimisation* failed would make `ssr: true` a liability rather than an
+ * improvement. The failure is logged rather than swallowed.
+ */
+async function _renderedHtml(component: string, pageObject: PageObject): Promise<string> {
+  const [prefix = "", suffix = ""] = _bustAssets(_htmlTemplate).split("<!-- @inertia -->");
+  try {
+    const { modPath, framework } = await resolvePageModule(_getPagesDir(), component);
+    const { body, head } = await renderInertiaPage(pageObject, modPath, framework);
+    // `body` is already the whole mount root — `renderInertiaPage` returns
+    // `pageScript + rootOpen + html + ROOT_CLOSE` for React, and Vue's SSR result
+    // carries its own root too. Wrapping it again emits two `<div id="app">` and
+    // two `data-page` scripts, and the client hydrates against the wrong one.
+    // Composed exactly as `inertiaStream` composes it, so the two cannot drift.
+    return injectHead(prefix, head) + body + suffix;
+  } catch (error) {
+    console.warn(
+      `[Inertia] SSR render failed for "${component}", serving the client-rendered ` +
+        `document instead: ${(error as Error).message}`,
+    );
+    return `${prefix}${rootOpen(false)}${ROOT_CLOSE}
+    ${pageScript(pageObject)}${suffix}`;
+  }
+}
 async function _inertia(component: string, props: Record<string, unknown>): Promise<void> {
   const ctx = RequestContext.get();
   const isInertiaRequest = ctx.request.headers.get("X-Inertia") === "true";
@@ -454,16 +495,25 @@ async function _inertia(component: string, props: Record<string, unknown>): Prom
     throw new InertiaTemplateNotLoadedError();
   }
-  // Inject pageObject into the HTML template. The root is empty — this path does
-  // not server-render the component, so it is deliberately *not* marked
-  // `data-server-rendered`: that flag tells the client to hydrate, and hydrating an
-  // empty div is a mismatch on every page. See `inertiaStream()` for the rendered
-  // form, and the "What a crawler sees" section of the Inertia docs for what this
-  // response contains.
-  const html = _bustAssets(_htmlTemplate).replace(
-    "<!-- @inertia -->",
-    `${rootOpen(false)}${ROOT_CLOSE}\n    ${pageScript(pageObject)}`,
-  );
+  // `inertia.ssr` renders the component here, on the first load, for every page.
+  //
+  // That is what the option is named for and what every Inertia adapter does with
+  // it — and until 1.13.4 it did not: the flag registered `POST /__ssr` and nothing
+  // in the request path consulted it, so an app that set `ssr: true` and read the
+  // documentation got exactly the empty root it had before. Server rendering was
+  // reachable only by rewriting each route to `Inertia.stream()`, one call site at
+  // a time, which is not what a global switch means.
+  const html = _ssrEnabled()
+    ? await _renderedHtml(component, pageObject)
+    : _bustAssets(_htmlTemplate).replace(
+        "<!-- @inertia -->",
+        // The root is empty, so it is deliberately *not* marked
+        // `data-server-rendered`: that flag tells the client to hydrate, and
+        // hydrating an empty div is a mismatch on every page. See the "What a
+        // crawler sees" section of the Inertia docs for what this contains.
+        `${rootOpen(false)}${ROOT_CLOSE}
+    ${pageScript(pageObject)}`,
+      );
   ctx.response = new Response(html, {
     headers: {