DOCSEARCHbyAlgolia
Submit Docs

Inertia.js Laravel Adapter

repository·3.x·Indexed 25 days ago

https://github.com/inertiajs/inertia-laravel

The Inertia.js Laravel Adapter enables the creation of single-page apps using classic server-side routing and controllers, bridging Laravel with frontend frameworks like Vue, React, or Svelte. It provides tools for managing Server-Side Rendering (SSR) via commands like inertia:start-ssr and inertia:check-ssr, middleware for sharing props and asset versioning, and a ResponseFactory for rendering components with advanced property types such as deferred and optional props.

Tokens
4.3K
Snippets
1
Records
39
Agent score
82%

What's inside inertia-laravel

  1. Handle SSR rendering failures

    3.x

    When the SSR engine fails to render a page, the HttpGateway handles the error by dispatching an SsrRenderFailed event. This event contains details such as the error message, error type, stack trace, and source location.

    By default, failures are caught and handled gracefully (returning null so the application falls back to client-side rendering). However, you can configure the adapter to throw an exception instead of failing silently, which is useful for E2E testing or strict environments.

    Set the following configuration key in config/inertia.php to enable exception throwing: inertia.ssr.throw_on_error (boolean)

  2. Configure the Inertia Middleware

    3.x

    To use Inertia in your Laravel application, you must register the Inertia\Middleware class in your application's HTTP middleware stack. This middleware handles asset versioning, shared props, SSR exclusions, and Inertia-specific response handling.

    You can extend this middleware to customize several key behaviors, such as defining shared props, setting the root template, or excluding specific paths from Server-Side Rendering (SSR).

  3. Configure Inertia via `config/inertia.php`

    3.x

    The adapter uses a configuration file located at config/inertia.php. This file controls how Inertia resolves pages and handles extensions.

    When you install the package, you should publish this configuration file to your application's config directory:

    php artisan vendor:publish --tag=inertia-config

    Key configuration areas include:

    • pages.paths: The directory paths where Inertia page files are located.
    • pages.extensions: The file extensions used for Inertia pages (e.g., vue, jsx).

  4. Use Inertia Blade directives and components

    3.x

    The Inertia Laravel adapter registers Blade directives and component namespaces to facilitate rendering Inertia applications within Laravel Blade templates.

    Blade Directives

    • @inertia: Compiles the root element for your Inertia application.
    • @inertiaHead: Compiles the head content for SSR (Server-Side Rendering).

    Blade Components

    Inertia components are available under the inertia namespace. You can use them in your Blade files to render specific Inertia views.

  5. Configure SSR server connection settings

    3.x

    The HttpGateway uses the following configuration keys from config/inertia.php to communicate with your SSR server:

    • inertia.ssr.enabled: (boolean) Whether SSR is enabled globally. Defaults to true.
    • inertia.ssr.url: (string) The production URL for the SSR server. Defaults to http://127.0.0.1:13714.
    • inertia.ssr.hot_url: (string) The URL used when Vite is running in hot mode. If not set, it attempts to read the URL from the Vite hot file.
    • inertia.ssr.ensure_bundle_exists: (boolean) If true, the gateway checks if an SSR bundle exists before attempting to dispatch. Defaults to true.
    • inertia.ssr.throw_on_error: (boolean) If true, an SsrException is thrown when rendering fails instead of falling back to client-side rendering.

  6. Add data to the root view with `withViewData()`

    3.x
    The withViewData() method allows you to pass data directly to the underlying Laravel Blade view (the root view) rather than to the Inertia page props. This is typically used for data that needs to be available at the very top level of your application, such as global configuration or metadata used by the root template.

  11. Configure SSR exclusion and disabling

    3.x

    The HttpGateway allows you to control when Server-Side Rendering (SSR) is applied to requests. You can exclude specific URL paths from SSR or disable SSR entirely based on a condition.

    • Exclude paths: Use except() to prevent SSR for specific routes. This is useful for routes that don't require SEO or are purely client-side.
    • Disable SSR: Use disable() to set a boolean or a Closure that determines if SSR should be active. If the closure returns true, SSR is disabled for that request.

    These settings are checked via the ssrIsEnabled() method before any dispatch attempt.