Asset Versioning

Asset versioning ensures clients receive updated assets after deployments. When the version changes, Inertia triggers a full page reload.

Automatic Versioning

inertia-sails automatically handles asset versioning by default:

With Shipwright

When using Shipwright, inertia-sails reads the .tmp/public/manifest.json file and generates an MD5 hash. The version automatically changes when any bundled asset changes.

Your assets change → manifest.json updates → version hash changes → clients get fresh assets

Without Shipwright

When Shipwright isn't available, inertia-sails uses the server startup timestamp as the version. This changes the version on each server restart.

How It Works

1. inertia-sails generates a version string
2. The version is included in every Inertia response
3. The client compares the version with its cached version
4. On GET Inertia requests, a mismatch returns 409 Conflict
5. The response includes X-Inertia-Location with the current URL
6. Inertia performs a full page visit to that URL
7. The browser fetches fresh assets

409 Conflict version responses are only sent for GET requests. Mutating requests continue through their normal submit and redirect flow.

Custom Version

Override automatic versioning with a custom version:

// config/inertia.js
module.exports.inertia = {
  version: 'v2.1.0'
}

Or use a function for dynamic versioning:

module.exports.inertia = {
  version: () => require('./package.json').version
}

Version Strategies

Strategy	Pros	Cons
Manifest hash (default)	Precise, automatic	Requires Shipwright
Timestamp (fallback)	Simple, automatic	Reloads on every restart
Package version	Semantic, controlled	Manual updates
Custom function	Flexible	More complexity

Best Practices

1. Use Automatic Versioning

For most apps, the automatic versioning is sufficient:

// config/inertia.js
module.exports.inertia = {
  rootView: 'app'
  // version is auto-detected
}

2. Avoid Manual Version Bumps

Don't manually update version numbers. Let the manifest hash handle it:

// Don't do this
module.exports.inertia = {
  version: 1 // Have to remember to bump this
}

3. Use Package Version for Major Releases

If you want version numbers that match your releases:

module.exports.inertia = {
  version: () => {
    const pkg = require('./package.json')
    return pkg.version
  }
}

Debugging

Check the current version in your browser's Network tab. Look for the X-Inertia-Version request header and the version value in the Inertia page object.

If versions mismatch on a GET Inertia request, you'll see a 409 Conflict response with X-Inertia-Location, followed by a full page visit.

Production Considerations

In production:

1. Build your assets with Shipwright
2. The manifest.json is generated with hashed filenames
3. inertia-sails reads this manifest to generate the version
4. Deploying new assets automatically updates the version

# Build for production
NODE_ENV=production npm run build

# Start server - version is auto-detected from manifest
npm start