Support stable Inertia.js v3 in inertia-sails and templates

[DominusKelvin]

Summary

Inertia.js v3 is now stable enough for Boring Stack investigation.

Verified on 2026-05-18:

• @inertiajs/core, @inertiajs/react, @inertiajs/vue3, and @inertiajs/svelte publish 3.1.1 as latest.
• The npm legacy tag points at 2.3.23, so v2 is still available while v3 is the active line.
• v3.0.0 shipped on 2026-03-25, and v3.1.1 shipped on 2026-05-07.

This issue tracks the work needed to make inertia-sails and the Boring Stack templates compatible with stable Inertia v3. The goal is to first support a normal client-rendered Inertia app, then treat SSR/Rsbuild plugin work as a follow-up phase.

Current Repo State

• packages/inertia-sails/package.json is 1.3.3 and implements the current v2-oriented Sails adapter.
• Templates currently pin Inertia client packages to v2 ranges:
  • templates/mellow-vue: @inertiajs/vue3@^2.0.3, inertia-sails@^1.0.1
  • templates/mellow-react: @inertiajs/react@^2.1.2, inertia-sails@^1.1.0
  • templates/mellow-svelte: @inertiajs/svelte@^2.0.3, inertia-sails@^1.1.0
  • templates/ascent-vue: @inertiajs/vue3@^2.2.15, inertia-sails@^1.1.0
  • templates/ascent-react: @inertiajs/react@^2.2.15, inertia-sails@^1.1.0
• The framework versions are mostly ready for v3 minimums: React templates already use React 19, Svelte uses Svelte 5, and Vue templates use Vue 3.

Audit Notes from inertia-sails

inertia-sails already has useful protocol pieces:

• Page rendering through lib/render.js and lib/helpers/build-page-object.js
• Request-scoped shared props and locals through lib/helpers/request-context.js
• Partial reload headers and prop filtering
• Optional, always, deferred, merge, deep merge, scroll, and once prop wrappers
• Validation error redirect handling
• X-Inertia-Location handling for location visits
• History encryption and clear-history request flags
• Flash data support
• Testing helpers in packages/inertia-sails/test.js

The main v3 gaps are protocol shape, initial HTML boot data, shared prop metadata, richer merge metadata, asset-version mismatch behavior, and tests/docs.

Phase 1 - Stable v3 Client Compatibility

inertia-sails Protocol Work

• Update lib/helpers/build-page-object.js so clearHistory and encryptHistory are only included in the page object when their value is true. v3 protocol marks both as omitted unless enabled.
• Add top-level sharedProps metadata to the page object. This should list top-level keys registered through sails.inertia.share() and sails.inertia.shareGlobally() so v3 instant visits can carry shared props correctly.
• Add or verify asset-version mismatch handling. inertia-sails defines X-Inertia-Version, and auto-generates versions from the Shipwright manifest, but the adapter should compare incoming X-Inertia-Version against the current version and return a 409 with X-Inertia-Location when assets are stale.
• Review lib/location.js against the v3 protocol. Existing 409 location visit and 303 redirects for PUT/PATCH/DELETE look aligned, but this should be covered by tests.
• Extend merge support in lib/props/merge-prop.js and lib/props/resolve-merge-props.js for v3 metadata:
  • mergeProps
  • prependProps
  • deepMergeProps
  • matchPropsOn
  • nested prop paths
  • reset behavior through X-Inertia-Reset
• Review whether preserveFragment should be exposed by inertia-sails, likely as a request-scoped helper similar to clearHistory().
• Review deferred prop rescue support. v3 protocol includes rescuedProps; current deferred props implementation does not appear to expose rescue metadata.
• Keep the existing validation error flow, but add v3 regression coverage around X-Inertia-Error-Bag and redirect-back behavior.
• Update packages/inertia-sails/test.js with assertions for new metadata: omitted false history flags, sharedProps, prependProps, matchPropsOn, rescuedProps if implemented, and asset-version mismatch responses.
• Decide package versioning. This likely needs a major inertia-sails release because the adapter output and template boot contract change.

Template Work

• Replace initial page boot markup in every views/app.ejs template. v3 uses a JSON script tag instead of the old root data-page attribute.

  <div id="app"></div>
  <script type="application/json" data-page="app"><%- JSON.stringify(page) %></script>

  Affected files:

  • templates/ascent-react/views/app.ejs
  • templates/ascent-vue/views/app.ejs
  • templates/mellow-react/views/app.ejs
  • templates/mellow-svelte/views/app.ejs
  • templates/mellow-vue/views/app.ejs

• Update packages/inertia-sails/README.md, which still documents <div id="app" data-page="...">.

• Bump template dependencies to stable v3 ranges, probably @inertiajs/*@^3.1.1 once the adapter changes land.

• Bump template inertia-sails dependency to the new compatible adapter release.

• Regenerate or update template lockfiles after dependency changes.

• Verify Rsbuild/Rspack page resolution with v3 ESM packages. Templates currently use this resolver inside bundled client code:

  resolve: (name) => require(`./pages/${name}`)

  This may still work through Rspack, but it needs a real build/runtime check.

• If the require() resolver breaks under v3 ESM, switch templates to an Rsbuild-compatible dynamic import/page resolver.

• Check for removed/renamed v3 client APIs. Initial grep did not find current template usage of router.cancel(), hideProgress(), revealProgress(), invalid, or exception event handlers, but keep this in the upgrade checklist.

create-sails / Generator Work

• Update any generator/template source that emits Inertia root markup or client imports.
• Ensure generated React, Vue, and Svelte apps use the new compatible package ranges.
• Add generator coverage or smoke tests so new apps boot with v3.

Phase 2 - Error Pages and Exceptions

• Design a Sails-friendly equivalent of Inertia v3 exception rendering for 403, 404, 500, and 503.
• Preserve the existing development error modal behavior for Inertia requests where appropriate.
• Add a config option under config/inertia.js, for example handleExceptions, that can return an Inertia page response or fall through to default Sails responses.
• Add default error page components to templates if we choose to ship this as part of the v3 support story.

Phase 3 - SSR and Rsbuild Plugin Investigation

Do not block basic v3 support on SSR. Track this as a follow-up once client-rendered v3 works.

• Compare @inertiajs/vite v3 behavior against Shipwright/Rsbuild needs.
• Decide whether we need an @inertiajs/rsbuild or Boring Stack-specific Rsbuild plugin.
• If needed, prototype SSR entry handling, dev SSR endpoint, production SSR build, and CSS collection through Rsbuild/Shipwright.
• Update inertia-sails SSR rendering only after the build-system story is clear.

Acceptance Criteria

• inertia-sails emits a v3-compatible page object.
• Initial non-Inertia HTML responses boot from the v3 JSON script tag.
• Inertia XHR responses, partial reloads, validation redirects, location visits, flash props, once props, deferred props, merge props, scroll props, and history flags have focused tests.
• At least one React, Vue, and Svelte template boots successfully with @inertiajs/*@3.x.
• Generated apps from create-sails use the v3-compatible template path.
• Docs and README examples no longer show the v2 data-page root attribute.

References

• https://github.com/inertiajs/inertia/releases/tag/v3.0.0
• https://github.com/inertiajs/inertia/releases/tag/v3.1.1
• https://inertiajs.com/docs/v3/getting-started/upgrade-guide
• https://inertiajs.com/docs/v3/core-concepts/the-protocol
• https://www.npmjs.com/package/@inertiajs/core

[DominusKelvin]

Additional docs scope: update the package README in this repo and the public Boring Stack docs at https://docs.sailscasts.com/boring-stack. The docs site should cover both the v3 protocol upgrade and the new error/exception handling path once implemented.

[DominusKelvin]

Response audit for the templates:

All five templates currently ship the same thin response wrappers:

• api/responses/inertia.js -> sails.inertia.render(req, res, data)
• api/responses/badRequest.js -> sails.inertia.handleBadRequest(req, res, optionalData)
• api/responses/inertiaRedirect.js -> sails.inertia.location(req, res, url)
• api/responses/serverError.js -> sails.inertia.handleServerError(req, res, error)
• api/responses/expired.js -> res.status(400).redirect('/link-expired')

Generator templates currently only cover inertia, inertiaRedirect, and badRequest.

What this means for v3:

• The thin inertia, badRequest, and inertiaRedirect response files can mostly stay stable if the adapter helpers are upgraded correctly.
• serverError.js should likely move to a generic exception handler once we add Inertia v3-style exception rendering, for example sails.inertia.handleException(req, res, { statusCode: 500, error }).
• The templates do not currently ship custom notFound.js or forbidden.js, even though many controllers use responseType: 'notFound' and responseType: 'forbidden'. To support in-app Inertia 404/403 pages, we should add these response files to every template and route them through the same new exception handler.
• expired.js should be reviewed. It currently claims content negotiation but always returns a 400 redirect to /link-expired. For Inertia visits, it may be better to route through sails.inertia.location() / inertiaRedirect semantics or render the existing link-expired Inertia page directly.
• The generator should gain templates for any new response files we decide to ship, likely notFound, forbidden, and maybe serverError if we want generator parity.
• Adapter-side handleBadRequest() / resolveValidationErrors() need v3 validation/error-bag regression tests. The template wrapper itself can stay thin, but the helper should own the protocol details.
• Adapter-side location() should be checked for v3 fragment redirect behavior (X-Inertia-Redirect) while preserving current X-Inertia-Location behavior for external/full reload redirects.

[DominusKelvin]

Progress update

Implementation work has started on feat/192-support-stable-inertia-js-v3-in-inertia-sails-and-templates.

Committed in boring-stack:

• 2bb0c01 feat(inertia-sails): support Inertia v3 protocol metadata

What landed:

• v3 root-view boot payload support in all templates using <script type="application/json" data-page="app"> plus safe < escaping
• asset-version mismatch handling for GET Inertia requests with 409 Conflict and X-Inertia-Location
• Vary: X-Inertia for Inertia JSON responses
• optional clearHistory / encryptHistory behavior so false flags are omitted
• sharedProps metadata
• v3 merge metadata support: mergeProps, prependProps, deepMergeProps, matchPropsOn
• nested append/prepend targets and item matching for merge props
• InfiniteScroll merge intent support via X-Inertia-Infinite-Scroll-Merge-Intent
• scroll props now merge the wrapped array path, e.g. users.data
• README updates and focused node test coverage

Verification:

• npm test in packages/inertia-sails passes: 20/20

Public docs branch in /Users/koo/Gringotts/687/docs.sailscasts.com:

• feat/192-support-inertia-v3-docs
• 5021b18 docs: document Inertia v3 adapter behavior

Docs updates cover:

• v3 root-view JSON script boot payload
• merge append/prepend/matchOn behavior
• InfiniteScroll metadata and merge intent
• asset version mismatch behavior
• hybrid Sails/EJS + Inertia error handling guidance
• custom response docs for badRequest, serverError, and hybrid 404/500 behavior

Docs verification:

• touched docs files pass Prettier check
• npm run build passes
• full npm run lint still reports unrelated pre-existing formatting warnings in docs/captain-vane/basic-usage.md and docs/sails-stash/cache-usage.md

Follow-up issues created while scoping the ecosystem work:

• Complete Sounding integration across templates after Inertia v3 support #195 Complete Sounding integration across templates after Inertia v3 support
• Update all templates to Shipwright 1.3.0 #196 Update all templates to Shipwright 1.3.0
• Investigate Precognition-style live validation for Boring Stack #197 Investigate Precognition-style live validation for Boring Stack
• Add a rich developer error experience for Boring Stack apps #198 Add a rich developer error experience for Boring Stack apps

[DominusKelvin]

Quick correction to the previous progress note: I formatted the two unrelated docs pages that were making full docs lint fail. npm run lint now passes in docs.sailscasts.com.

[DominusKelvin]

Draft PRs are open:

• Implementation: Support Inertia v3 protocol metadata #199
• Public docs: Document Inertia v3 adapter behavior docs.sailscasts.com#71

Validation after cleanup:

• npm test passes in packages/inertia-sails
• npm run lint passes in docs.sailscasts.com
• npm run build passes in docs.sailscasts.com

[DominusKelvin]

Migration smoke update

The local inertia-sails@1.4.0 tarball has now been tested in /Users/koo/Gringotts/687/africanengineer.com on a temporary branch with:

• @inertiajs/vue3@3.1.1
• inertia-sails installed from the packed inertia-sails-1.4.0.tgz
• the v3 initial page shape in views/app.ejs
• the required axios peer dependency for @inertiajs/core@3.x

AfricanEngineer verification:

• npm run lint passes
• npm test passes: unit 4/4, functional 12/12, e2e 6/6

One useful finding: Inertia v3's core package declares axios as a peer dependency. Without installing it, Shipwright/Rsbuild surfaces an overlay error from @inertiajs/core, which can block real browser interactions. The templates now include axios alongside the v3 client adapters.

What to look for when reviewing/testing

• Initial full-page loads should render from an empty #app plus <script type="application/json" data-page="app">.
• Inertia JSON responses should include Vary: X-Inertia and omit false history flags.
• Stale X-Inertia-Version GET requests should return 409 plus X-Inertia-Location.
• Form validation should still flow through badRequest into form.errors.
• Redirects after mutations should preserve Inertia behavior, including external/location redirects.
• Partial reloads, deferred props, optional props, once props, scroll props, and merge metadata should still resolve correctly.
• React templates should no longer use v2-style arrow-function persistent layouts.
• Hybrid apps should keep regular Sails/EJS pages working beside Inertia pages.
• Browser console should be free of hydration, missing-peer, layout, or module-resolution errors.
• Shipwright production/dev builds should continue producing the manifest used for asset versioning.

Follow-up captured

Selective Inertia SSR is now tracked separately in #200 so it does not block this v3 protocol migration.