Inertia.js visit(): Achieving Progressive Enhancement with Server-Side Navigation

The Problem: Conditional Server Redirects vs. SPA State Preservation

When server logic (e.g., validation failure, authentication check) requires navigation, the challenge is forcing a client-side update (SPA behavior) rather than a full browser page reload. The useful takeaway is that Inertia's visit() method allows the server to trigger a client-side transition by returning a specific HTML fragment and headers, ensuring progressive enhancement works reliably.

Design Requirements for Server-Side Visit

For visit() to function as intended, the server must adhere to strict output rules:

• The response body must be an HTML fragment containing only the component's markup, not a full document (no <html> or <head> tags).
• The response must include the X-Inertia header for Inertia to process it; otherwise, standard browser navigation occurs.
• GET and POST are supported by default; PUT/PATCH/DELETE require the _method parameter override on the server.

Trust and Data Boundaries

This feature crosses the server-client trust boundary. The server must guarantee the response structure. If the server returns a full page layout instead of a fragment, Inertia fails to update the component, and the user sees a broken layout, effectively degrading the experience.

Operational Verification

Verify the mechanism using browser developer tools:

1. Inspect the Network tab for the presence of the X-Inertia header on the response.
2. Confirm the response body is strictly the component markup, not a complete HTML document.
3. Test the difference: a standard Location header forces full browser navigation, whereas X-Inertia Location triggers only the Inertia client-side visit.

Failure Modes and Design Changes

The design shifts if:

• The X-Inertia header is missing: The browser follows the Location header normally (full reload).
• A full page HTML response is returned: Inertia replacement fails.
• The server framework does not support the _method parameter: Non-GET/POST requests will fail without custom handling.

Concrete Example: Controller Logic

In a framework like Laravel, the controller logic must conditionally return the Inertia response based on expected client handling:

use Inertia\Inertia;\n\npublic function store(Request $request)\n{\n    // Validation logic here...\n    $post = Post::create(/* validated data */);\n\n    // Check if the request context suggests Inertia processing is expected\n    if ($request->header('X-Inertia')) {\n        // Triggers client-side Inertia visit\n        return Inertia::location(route('posts.show', $post));\n    }\n\n    // Fallback for non-Inertia contexts\n    return redirect()->route('posts.show', $post);\n}

Practical Check and Limitations

To confirm success, check that the response includes X-Inertia: true and that the page updates via component replacement without a full page refresh. A limitation is that visit() relies entirely on the server correctly generating component fragments and managing headers; framework-specific middleware or request handling must be verified for method overrides.