@zerotal/inertia 1.14.3 → 1.15.0

package/CHANGELOG.md

@@ -8,6 +8,27 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.0] — 2026-09-04
+
+### Added
+
+- **`bun zt route:types` now regenerates the page registry too.** Adding a page and rendering
+  it failed typecheck with `TS2345: Argument of type '"ops/orders"' is not assignable to
+parameter of type 'PageName'` — accurate and unhelpful, because it reads as a mistyped page
+  name when the actual state is a registry that has not been rebuilt. `route:types` is the
+  command whose name says it fixes that and used to regenerate only the routes half.
+
+  `InertiaProvider` registers `generatePageRegistry` through core's `registerTypeGenerator`,
+  so one command refreshes both, and `route:types --check` gates on both in CI. `PageName`
+  also carries a doc comment saying what to run, so the editor hover answers the question the
+  compiler error raises.
+
+### Fixed
+
+- **`generatePageRegistry` rewrote `pages.generated.ts` even when nothing had changed**,
+  churning its mtime on every dev rebuild and at every production boot — which is what a file
+  watcher keys on. It now compares before writing.
+
 ## [1.14.0] — 2026-09-01
 
 ### Changed — **BREAKING**

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class AlwaysProp = {

package/package.json

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

package/src/PageRegistry.ts

@@ -11,7 +11,7 @@
  * Import paths in the generated file are computed relative to the generated
  * file's own location (`resources/js/`), so any pages directory works.
  *
- * Run via: bun zt inertia:build
+ * Run via: bun zt route:types (or bun zt inertia:build, which also bundles).
  * Or automatically during InertiaProvider.onBooted() in production.
  */
 import { config } from "@zerotal/core";
@@ -24,21 +24,39 @@ import { DEFAULT_PAGES_DIR } from "./config.ts";
 const GENERATED_DIR = "resources/js";
 const GENERATED_FILE = `${GENERATED_DIR}/pages.generated.ts`;
 
+/**
+ * What a registry generation did, for `route:types` to report and `--check` to
+ * gate on.
+ *
+ * @internal Returned by the `@internal` {@link generatePageRegistry}; the shape
+ * core's type-generator hook expects, not app-facing API.
+ */
+export interface PageRegistryResult {
+  /** The generated file, relative to the project root. */
+  file: string;
+  /** Page count, phrased for a summary line. */
+  summary: string;
+  /** Whether the file on disk differed from what the scan produced. */
+  changed: boolean;
+}
+
 /**
  * Scan the pages directory and (re)write `resources/js/pages.generated.ts`, a map of
  * page name → dynamic `import()` thunk that `Bun.build({ splitting: true })` turns into
- * one lazy-loaded chunk per page. Called by the `inertia:build` / `make:page` commands
- * and by `InertiaProvider` at boot in production.
+ * one lazy-loaded chunk per page. Called by the `route:types` / `inertia:build` /
+ * `make:page` commands and by `InertiaProvider` at boot in production.
  *
  * @param cwd - Project root to scan and write relative to. Defaults to `process.cwd()`.
  * @param pagesDir - Pages directory relative to `cwd`. Defaults to the `inertia.pagesDir` config (`resources/js/pages`).
- * @returns Resolves once the registry file has been written.
+ * @param options - `check: true` compares against disk and reports without writing.
+ * @returns What was generated, and whether it differed from the file on disk.
  * @internal Framework scaffolding; not called from application code.
  */
 export async function generatePageRegistry(
   cwd = process.cwd(),
   pagesDir: string = config.safe("inertia.pagesDir", DEFAULT_PAGES_DIR),
-): Promise<void> {
+  options: { check?: boolean } = {},
+): Promise<PageRegistryResult> {
   // Normalise to a cwd-relative POSIX path without a trailing slash.
   const dir = pagesDir.replace(/\\/g, "/").replace(/\/+$/, "");
 
@@ -79,7 +97,7 @@ export async function generatePageRegistry(
 
   const content = [
     "// Auto-generated by @zerotal/inertia — do not edit manually.",
-    "// Regenerate with: bun zt inertia:build",
+    "// Regenerate with: bun zt route:types  (or bun zt inertia:build, which also bundles)",
     "//",
     "// IMPORTANT: These are dynamic import THUNKS, not static imports.",
     "// Bun.build with splitting:true creates one .js chunk per page.",
@@ -107,9 +125,29 @@ export async function generatePageRegistry(
     "",
   ].join("\n");
 
-  await Bun.write(`${cwd}/${GENERATED_FILE}`, content);
+  // Compare before writing. The file is regenerated on every dev rebuild and at
+  // boot in production, and rewriting identical bytes churns the mtime — which
+  // is what a file watcher keys on, so the write would retrigger the rebuild
+  // that produced it. It also gives `route:types --check` something to gate on.
+  const target = `${cwd}/${GENERATED_FILE}`;
+  const existing = await Bun.file(target)
+    .text()
+    .catch(() => null);
+  const changed = existing !== content;
+
+  if (changed && options.check !== true) {
+    await Bun.write(target, content);
+  }
+
+  if (changed) {
+    frameworkLog("inertia").info(`Generated page registry: ${thunks.length} pages`, {
+      pages: thunks.length,
+    });
+  }
 
-  frameworkLog("inertia").info(`Generated page registry: ${thunks.length} pages`, {
-    pages: thunks.length,
-  });
+  return {
+    file: GENERATED_FILE,
+    summary: `${thunks.length} page${thunks.length === 1 ? "" : "s"}`,
+    changed,
+  };
 }

package/src/index.ts

@@ -64,6 +64,7 @@ export { PrecognitionMiddleware } from "./middleware/PrecognitionMiddleware.ts";
 export { sharedProps } from "./SharedProps.ts";
 export { assetVersion, setAssetVersion } from "./version.ts";
 export { generatePageRegistry } from "./PageRegistry.ts";
+export type { PageRegistryResult } from "./PageRegistry.ts";
 // The typed page registry: `InertiaPageRegistry` is what `pages.generated.ts`
 // augments, `SharedProps` is what the app declares for `Inertia.share()`.
 export type {

package/src/pages.ts

@@ -88,12 +88,31 @@ type AllSharedProps = SharedProps & BuiltInSharedProps;
 /** The generated `pages` map, or an empty map before the registry exists. */
 type PageModules = InertiaPageRegistry extends { pages: infer Map } ? Map : Record<never, never>;
 
-/** Every page name in the generated registry. `never` until it is generated. */
+/**
+ * Every page name in the generated registry. `never` until it is generated.
+ *
+ * **If a name you can see on disk is rejected here, the registry is stale, not
+ * the name** — `resources/js/pages.generated.ts` is written by a scan of the
+ * pages directory and does not know about a file added since. Regenerate it:
+ *
+ * ```sh
+ * bun zt route:types
+ * ```
+ *
+ * TypeScript reports the mismatch as TS2345 ("not assignable to parameter of
+ * type 'PageName'"), which reads like a typo, so this note is here to be the
+ * first thing the hover shows.
+ */
 export type PageName = Extract<keyof PageModules, string>;
 
 /**
  * What the Inertia helpers accept as a component name: the generated page names
  * once the registry exists, any string before that.
+ *
+ * The `never` fallback is a bootstrap — a new app type-checks before its first
+ * build — but it does mean page names are unchecked until the registry exists
+ * once, so the first error of this kind arrives after a build that succeeded.
+ * See {@link PageName} if a name you can see on disk is being rejected.
  */
 export type PageTarget = [PageName] extends [never] ? string : PageName;
 

package/src/provider/InertiaProvider.ts

@@ -1,4 +1,5 @@
 import { ServiceProvider, Router, ConfigError, ThrottleMiddleware } from "@zerotal/core";
+import { registerTypeGenerator } from "@zerotal/core/commands";
 import {
   registerDevBuildHook,
   pruneBuildOutput,
@@ -132,6 +133,14 @@ export class InertiaProvider extends ServiceProvider {
     // trigger a full pages-manifest sync + asset rebuild without @zerotal/core
     // importing @zerotal/inertia (which would create a circular dependency).
     const cwd = process.cwd();
+
+    // Same inversion, for `bun zt route:types`. The page registry and the route
+    // map are both "types generated from the file tree" and go stale on the same
+    // edits, but only the routes half was wired to the command named for it —
+    // so adding a page, running `route:types`, and getting the same `PageName`
+    // error back sent people looking at their page name instead of the registry.
+    registerTypeGenerator("inertia", (options) => generatePageRegistry(cwd, undefined, options));
+
     registerDevBuildHook("inertia", async () => {
       await generatePageRegistry(cwd);
       const plugins = [...(await detectCssPlugins(cwd)), ...(await detectVuePlugin(cwd))];