npm - @zerotal/inertia - Versions diffs - 1.10.0 → 1.11.0 - Mend

@zerotal/inertia 1.10.0 → 1.11.0

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 (6) hide show

package/CHANGELOG.md +35 -0
package/api-surface.md +10 -0
package/package.json +4 -3
package/src/commands/InertiaBuildCommand.ts +14 -0
package/src/ssr/renderPage.ts +39 -2
package/src/testing.ts +97 -0

package/CHANGELOG.md CHANGED Viewed

@@ -8,6 +8,41 @@ follows the Zerotal monorepo's unified versioning.
 ## [Unreleased]
+## [1.11.0] — 2026-08-31
+### Added
+- **`@zerotal/inertia/testing` — `renderPage()`.** `assertInertia("home")` proves the
+  _server_ named a component and handed it props. It proves nothing about the
+  component, and a page can throw on its first paint while every such test passes: the
+  route answers `200`, the payload is correct, and the failure happens in a browser
+  the suite never opened. An app shipped a blank page to production with **614 passing
+  tests** exactly that way — a layout callback read `page.props`, which the callback
+  is not given.
+  `renderPage(Component, props, { shared })` builds the tree through Inertia's own
+  `<App>`, so `usePage()`, `<Head>` and a persistent layout all behave as they do in
+  the browser, and lets whatever it throws escape. It is not a DOM — `useEffect` does
+  not run — which is the point: it proves the tree _builds_, which is what nothing
+  else checked.
+### Documented
+- **[Persistent layouts](/docs/inertia/rendering#persistent-layouts)**, which this
+  package documented nowhere — not in the README, not in `api-surface.md`. The
+  callback is handed the page **element**, not the page props, so the natural
+  `(page) => <Layout search={page.props.search}>{page}</Layout>` throws on the first
+  paint and only in a browser. The page now shows the `usePage()` form and says why
+  the wrong one typechecks.
+### Fixed
+- **`zt inertia:build` fails when it produces nothing.** A build could report success
+  with zero artefacts, and that is the shape that reaches production: the deploy sees
+  exit 0, restarts, and serves a page with no script and no stylesheet. The health
+  check passes — the server is fine and the HTML is fine, there is just nothing in
+  it. An app had to assert the files exist in its own deploy script to catch it.
 ## [1.10.0] — 2026-08-30
 ### Fixed

package/api-surface.md CHANGED Viewed

@@ -319,3 +319,13 @@ type RenderArgs = [props?: Record<string, unknown>]
 type RenderProps = {    [x: string]: unknown;}
 type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>
+## ./testing  `(./src/testing.ts)`
+function renderPage = (component: unknown, props?: Record<string, unknown>, options?: RenderPageOptions) => Promise<string>
+interface RenderPageOptions = {
+  component?: string | undefined
+  shared?: Record<string, unknown> | undefined
+  url?: string | undefined
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/inertia",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -8,7 +8,8 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -33,7 +34,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0"
+    "@zerotal/core": "1.11.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",

package/src/commands/InertiaBuildCommand.ts CHANGED Viewed

@@ -79,6 +79,20 @@ export class InertiaBuildCommand extends Command {
       throw new Error("Frontend build failed.");
     }
+    // `success` with no artefacts is not a build, and it is the shape that reaches
+    // production: a deploy runs this, sees exit 0, restarts, and serves a page with
+    // no script and no stylesheet. The health check passes — the server is fine, the
+    // HTML is fine, there is simply nothing in it. An app had to assert the files
+    // exist in its own deploy script to catch it, which is the framework's job.
+    if (result.outputs.length === 0) {
+      throw new Error(
+        `Frontend build reported success and produced no files ` +
+          `(entry point: resources/js/app.tsx). An empty output directory serves a ` +
+          `page with no script and no stylesheet, which a health check cannot tell ` +
+          `from a working one.`,
+      );
+    }
     // Chunks are named after their content, so the ones this build replaced
     // would otherwise stay behind — and ship.
     //

package/src/ssr/renderPage.ts CHANGED Viewed

@@ -182,6 +182,23 @@ export async function _prepareReactRender(
     _importInertiaReact(inertiaReactSpecifier),
   ]);
+  return _elementFor(reactMod, inertiaReact, page, pageMod.default);
+}
+/**
+ * Wrap an already-resolved page component in Inertia's `<App>`.
+ *
+ * Split out so a test can render a component it imported directly, without a pages
+ * directory or a module path — see `@zerotal/inertia/testing`.
+ *
+ * @internal
+ */
+function _elementFor(
+  reactMod: ReactModule,
+  inertiaReact: InertiaReactModule,
+  page: SsrPage,
+  component: unknown,
+): PreparedReactRender {
   let head: string[] = [];
   // `<App>` owns the head manager, the page context and the layout resolution —
@@ -191,8 +208,8 @@ export async function _prepareReactRender(
   // whichever renderer we were handed to has produced its shell.
   const element = reactMod.createElement(inertiaReact.App, {
     initialPage: page,
-    initialComponent: pageMod.default,
-    resolveComponent: () => pageMod.default,
+    initialComponent: component,
+    resolveComponent: () => component,
     onHeadUpdate: (elements: string[]) => {
       head = elements;
     },
@@ -201,6 +218,26 @@ export async function _prepareReactRender(
   return { element, head: () => head };
 }
+/**
+ * Build the `<App>` element for a component the caller already has.
+ *
+ * @param page - The `{ component, props, url }` page to render.
+ * @param component - The page component itself.
+ * @internal
+ */
+export async function _prepareComponentRender(
+  page: SsrPage,
+  component: unknown,
+): Promise<PreparedReactRender> {
+  const reactSpecifier = "react";
+  const inertiaReactSpecifier = "@inertiajs/react";
+  const [reactMod, inertiaReact] = await Promise.all([
+    import(reactSpecifier) as Promise<ReactModule>,
+    _importInertiaReact(inertiaReactSpecifier),
+  ]);
+  return _elementFor(reactMod, inertiaReact, page, component);
+}
 /**
  * Import `@inertiajs/react`, turning "not installed" into a sentence that says what
  * to do about it.

package/src/testing.ts ADDED Viewed

@@ -0,0 +1,97 @@
+/**
+ * `@zerotal/inertia/testing` — render a page component the way a browser will.
+ *
+ * ## The gap this fills
+ *
+ * `assertInertia("home")` proves the *server* named a component and handed it props.
+ * It proves nothing about the component. A page can throw on its first paint — a
+ * destructured prop that is not there, a layout callback reading `page.props` that
+ * the callback never receives — and the route still answers `200` with a correct
+ * payload, because the throw happens in a browser that the test never opened.
+ *
+ * An app shipped a blank `/mail` to production with **614 passing tests**. Every one
+ * of them asserted a value or a status code. The console said
+ * `Cannot read properties of undefined (reading 'search')`, from a layout callback,
+ * on a page whose Inertia payload was perfect.
+ *
+ * {@link renderPage} proves one thing and one thing only: that the component tree
+ * can be built without throwing. That is precisely the thing nothing else checks,
+ * and it is about forty lines an app should not have to write.
+ *
+ * ## What it does not do
+ *
+ * It is not a DOM. Nothing here clicks, and `useEffect` does not run — this is
+ * `renderToString`, so it exercises the render pass. For assertions about behaviour
+ * after paint, use the browser harness in `@zerotal/testing/browser`.
+ *
+ * @example
+ * ```ts
+ * import { renderPage } from "@zerotal/inertia/testing";
+ * import Home from "../resources/js/pages/home.tsx";
+ *
+ * test("home renders", async () => {
+ *   await renderPage(Home, { title: "Hello" });
+ * });
+ * ```
+ *
+ * @module
+ */
+import { _prepareComponentRender } from "./ssr/renderPage.ts";
+/** Extras a page render may need beyond its own props. */
+export interface RenderPageOptions {
+  /**
+   * Shared props the app's `Inertia.share()` would have added — `auth`, `flash`,
+   * `errors`, and anything else a layout reads. A page that destructures one of
+   * these throws without it, which is a real failure but rarely the one you are
+   * testing for, so seed the shape your app actually shares.
+   */
+  shared?: Record<string, unknown> | undefined;
+  /** The URL the page believes it is at. Some layouts branch on it. Default `"/"`. */
+  url?: string | undefined;
+  /** The component name recorded in the page object. Default `"page"`. */
+  component?: string | undefined;
+}
+/**
+ * Render an Inertia page component to HTML, throwing whatever it throws.
+ *
+ * Renders through `@inertiajs/react`'s own `<App>`, so `usePage()`, `<Head>` and a
+ * persistent layout all behave as they do in the browser — a layout attached with
+ * `Page.layout` is resolved and rendered too, which is the case worth catching.
+ *
+ * @param component - The page component, imported directly.
+ * @param props - The props the server would send. Merged over `options.shared`.
+ * @param options - Shared props, URL and component name.
+ * @returns The rendered HTML, for a `toContain` if you want one.
+ * @throws Whatever the component throws, unchanged — the point is that it surfaces.
+ *
+ * @example
+ * ```ts
+ * const html = await renderPage(Profile, { user }, { shared: { auth: { user } } });
+ * expect(html).toContain(user.name);
+ * ```
+ */
+export async function renderPage(
+  component: unknown,
+  props: Record<string, unknown> = {},
+  options: RenderPageOptions = {},
+): Promise<string> {
+  const page = {
+    component: options.component ?? "page",
+    props: { ...(options.shared ?? {}), ...props },
+    url: options.url ?? "/",
+    version: "test",
+  };
+  const { element } = await _prepareComponentRender(page, component);
+  // Specifier via a variable: `react-dom/server` is an optional peer, and a Vue app
+  // type-checking this package must not be asked for a module it will never install.
+  const reactServerSpecifier = "react-dom/server";
+  const serverMod = (await import(reactServerSpecifier)) as {
+    renderToString: (element: unknown) => string;
+  };
+  return serverMod.renderToString(element);
+}