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.

Scaffold with create-inertiacore

InertiaCore maintains a scaffolder that wires up AspNetCore.InertiaCore, Vite, and your frontend framework of choice (Vue, React, or Svelte) in one step:

npm init inertiacore@latest
# or
npx create-inertiacore@latest

This is the fastest way to start a new InertiaCore project. If you’d prefer to add InertiaCore to an existing app, follow the manual steps below.

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.

VueReactSvelte

npm install vue @vitejs/plugin-vue

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

VueReactSvelte

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

The @inertiajs/vite plugin supports Vite 7 and Vite 8.

1. Install dependencies

   Install the Inertia client-side adapter and Vite plugin.

   VueReactSvelte

   npm install @inertiajs/vue3 @inertiajs/vite

2. Configure Vite

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

   import inertia from '@inertiajs/vite'
   import laravel from 'laravel-vite-plugin'
   import { defineConfig } from 'vite'
   
   export default defineConfig({
       plugins: [
           laravel({
               input: ['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.

   VueReactSvelte

   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.

VueReactSvelte

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

An object may also be provided for more control over how pages are resolved. You only need to include the options you wish to customize.

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.

Customizing the App

Sometimes you may wish to customize the app instance, for example to register plugins, wrap with providers, or set context values. Pass the withApp callback to createInertiaApp to hook into the app before it renders.

VueReactSvelte

import { createInertiaApp } from '@inertiajs/vue3'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
    // ...
})

createInertiaApp({
    withApp(app) {
        app.use(i18n)
    },
})

The callback receives the Vue app instance, allowing you to call app.use(), app.provide(), app.component(), and any other app-level method.

The callback receives the React element and must return a new element. This is where you may wrap your app with context providers.

The callback receives a Map that serves as Svelte’s component context. Values set here are accessible in your components via getContext().

A second { ssr } argument is also available, allowing you to conditionally apply logic based on the rendering environment.

VueReactSvelte

createInertiaApp({
    withApp(app, { ssr }) {
        app.use(i18n)

        if (!ssr) {
            app.use(browserOnlyPlugin)
        }
    },
})

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.

Note

A manual setup callback prevents the Vite plugin from auto-generating SSR handling. You should create a separate SSR entry point and update your app to use client-side hydration.

VueReactSvelte

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.

VueReactSvelte

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.

VueReactSvelte

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.

VueReactSvelte

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.