Client-Side Setup

Once you have your server-side framework configured, you then need to setup your client-side framework. Inertia currently provides support for React, Vue, and Svelte.

Laravel Starter Kits

Laravel’s starter kits provide out-of-the-box scaffolding for new Inertia applications.

These starter kits are the absolute fastest way to start building a new Inertia project using Laravel and Vue or React. However, if you would like to manually install Inertia into your application, please consult the documentation below.

Start building

Prerequisites

Inertia requires your client-side framework and its corresponding Vite plugin to be installed and configured. You may skip this section if your application already has these set up.

Vue

npm install vue @vitejs/plugin-vue

Then, add the framework plugin to your vite.config.js file.

Vue

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            refresh: true,
        }),
        vue(),
    ],
})

For more information on configuring these plugins, consult Laravel’s Vite documentation.

Installation

1. Install dependencies

   Install the Inertia client-side adapter and Vite plugin.

   Vue

   npm install @inertiajs/vue3 @inertiajs/vite
   
2. Configure Vite

   Add the Inertia plugin to your vite.config.js file.

   vite.config.js

   import inertia from '@inertiajs/vite'
   import laravel from 'laravel-vite-plugin'
   import { defineConfig } from 'vite'
   
   export default defineConfig({
       plugins: [
           laravel({
               input: ['resources/css/app.css', 'resources/js/app.js'],
               refresh: true,
           }),
           inertia(),
       ],
   })
   
3. Initialize the Inertia app

   Update your main JavaScript file to boot your Inertia app. The Vite plugin handles page resolution and mounting automatically, so a minimal entry point is all you need.

   Vue

   import { createInertiaApp } from '@inertiajs/vue3'
   
   createInertiaApp()
   

   The plugin generates a default resolver that looks for pages in both ./pages and ./Pages directories, and the app mounts automatically.

React Strict Mode

The React adapter supports enabling React’s Strict Mode via the strictMode option.

createInertiaApp({
    strictMode: true,
    // ...
})

Pages Shorthand

You may use the pages shorthand to customize which directory to search for page components.

Vue

createInertiaApp({
    pages: './AppPages',
    // ...
})

An object may also be provided for more control over how pages are resolved.

createInertiaApp({
    pages: {
        path: './Pages',
        extension: '.tsx',
        lazy: true,
        transform: (name, page) => name.replace('/', '-'),
    },
})

Option	Description
path	The directory to search for page components.
extension	A string or array of file extensions (e.g., '.tsx' or ['.tsx', '.jsx']). Defaults to your framework’s extension.
lazy	Whether to lazy-load page components. Defaults to true. See code splitting.
transform	A callback that receives the page name and page object, returning a transformed name.

Manual Setup

If you prefer not to use the Vite plugin, you may provide the resolve and setup callbacks manually. The resolve callback tells Inertia how to load a page component and receives the component name and the full page object. The setup callback initializes the client-side framework.

Vue

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.vue')
        return pages[`./Pages/${name}.vue`]()
    },
    setup({ el, App, props, plugin }) {
        createApp({ render: () => h(App, props) })
            .use(plugin)
            .mount(el)
    },
})

By default, page components are lazy-loaded, splitting each page into its own bundle. To eagerly bundle all pages into a single file instead, see the code splitting documentation.

The laravel-vite-plugin package also provides a resolvePageComponent helper that may be used to resolve page components.

Vue

import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

resolve: name => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),

Configuring Defaults

You may pass a defaults object to createInertiaApp() to configure default settings for various features. You don’t have to pass a default for every key, just the ones you want to tweak.

createInertiaApp({
  defaults: {
    form: {
      recentlySuccessfulDuration: 5000,
    },
    prefetch: {
      cacheFor: "1m",
      hoverDelay: 150,
    },
    visitOptions: (href, options) => {
      return {
        headers: {
          ...options.headers,
          "X-Custom-Header": "value",
        },
      };
    },
  },
  // ...
});

The visitOptions callback receives the target URL and the current visit options, and should return an object with any options you want to override. For more details on the available configuration options, see the forms, prefetching, and manual visits documentation.

Updating Configuration at Runtime

You may also update configuration values at runtime using the exported config instance. This is particularly useful when you need to adjust settings based on user preferences or application state.

Vue

import { config } from "@inertiajs/vue3";

// Set a single value using dot notation...
config.set("form.recentlySuccessfulDuration", 1000);
config.set("prefetch.cacheFor", "5m");

// Set multiple values at once...
config.set({
  "form.recentlySuccessfulDuration": 1000,
  "prefetch.cacheFor": "5m",
});

Defining a Root Element

By default, Inertia assumes that your application’s root template has a root element with an id of app. If your application’s root element has a different id, you can provide it using the id property.

createInertiaApp({
  id: "my-app",
  // ...
});

If you change the id of the root element, be sure to update it server-side as well.

HTTP Client

Unlike Inertia 2 and earlier, Inertia 3 uses a built-in XHR client for all requests. No additional HTTP libraries like Axios are required.

Using Axios

You may provide the axiosAdapter as the http option when creating your Inertia app. This is useful when your application requires a custom Axios instance.

import { axiosAdapter } from '@inertiajs/core'

createInertiaApp({
  http: axiosAdapter(),
  // ...
})

A custom Axios instance may also be provided to the adapter.

import axios from 'axios'
import { axiosAdapter } from '@inertiajs/core'

const instance = axios.create({
  // ...
})

createInertiaApp({
  http: axiosAdapter(instance),
  // ...
})

Interceptors

The built-in XHR client supports interceptors for modifying requests, inspecting responses, or handling errors. These interceptors apply to all HTTP requests made by Inertia, including those from the router, useForm, <Form>, and useHttp.

Vue

import { http } from '@inertiajs/vue3'

const removeRequestHandler = http.onRequest((config) => {
  config.headers['X-Custom-Header'] = 'value'
  return config
})

const removeResponseHandler = http.onResponse((response) => {
  console.log('Response status:', response.status)
  return response
})

const removeErrorHandler = http.onError((error) => {
  console.error('Request failed:', error)
})

// Remove a handler when it's no longer needed...
removeRequestHandler()

Each on* method returns a cleanup function that removes the handler when called. Request handlers receive the request config and must return it (modified or not). Response handlers receive the response and must also return it. Handlers may be asynchronous.

Custom HTTP Client

For full control over how requests are made, you may provide a completely custom HTTP client via the http option. A custom client must implement the request method, which receives an HttpRequestConfig and returns a promise resolving to an HttpResponse. Review the xhrHttpClient.ts source for a reference implementation.