Client-Side Setup - Inertiajs

import V3BetaWarning from "/snippets/v3-beta-warning.mdx"; import { ReactSpecific } from "/snippets/react-specific.jsx" import { SvelteSpecific } from "/snippets/svelte-specific.jsx" import { VueSpecific } from "/snippets/vue-specific.jsx"

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.

<Card icon="laravel" title="Laravel Starter Kits" href="https://laravel.com/docs/starter-kits" arrow="true" cta="Start building"

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.

</Card>

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.

<CodeGroup> ```bash Vue icon="vuejs" npm install vue @vitejs/plugin-vue ```

bash

npm install react react-dom @vitejs/plugin-react

bash

npm install svelte @sveltejs/vite-plugin-svelte

</CodeGroup>

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

<CodeGroup> ```js Vue icon="vuejs" 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(), ], })


```js React icon="react"
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import react from '@vitejs/plugin-react'

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

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import { svelte } from '@sveltejs/vite-plugin-svelte'

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

</CodeGroup>

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

Installation

<Steps> <Step title="Install dependencies"> Install the Inertia client-side adapter and Vite plugin.

    <CodeGroup>
    ```bash Vue icon="vuejs"
    npm install @inertiajs/vue3 @inertiajs/vite
    ```

    ```bash React icon="react"
    npm install @inertiajs/react @inertiajs/vite
    ```

    ```bash Svelte icon="s"
    npm install @inertiajs/svelte @inertiajs/vite
    ```
    </CodeGroup>
</Step>

<Step title="Configure Vite">
    Add the Inertia plugin to your `vite.config.js` file.

    ```js 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(),
        ],
    })
    ```
</Step>

<Step title="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.

    <CodeGroup>
    ```js Vue icon="vuejs"
    import { createInertiaApp } from '@inertiajs/vue3'

    createInertiaApp()
    ```

    ```jsx React icon="react"
    import { createInertiaApp } from '@inertiajs/react'

    createInertiaApp()
    ```

    ```js Svelte icon="s"
    import { createInertiaApp } from '@inertiajs/svelte'

    createInertiaApp()
    ```
    </CodeGroup>

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

</Steps>

React Strict Mode

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

jsx

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

Pages Shorthand

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

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

jsx

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

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

</CodeGroup>

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.

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.

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

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

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

jsx

import { createInertiaApp } from '@inertiajs/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()

createInertiaApp({
    withApp(app) {
        return (
            <QueryClientProvider client={queryClient}>
                {app}
            </QueryClientProvider>
        )
    },
})

import { createInertiaApp } from '@inertiajs/svelte'

createInertiaApp({
    withApp(context) {
        context.set('theme', 'dark')
    },
})

</CodeGroup> <VueSpecific> The callback receives the Vue app instance, allowing you to call `app.use()`, `app.provide()`, `app.component()`, and any other app-level method. </VueSpecific> <ReactSpecific> The callback receives the React element and must return a new element. This is where you may wrap your app with context providers. </ReactSpecific> <SvelteSpecific> The callback receives a `Map` that serves as Svelte's component context. Values set here are accessible in your components via `getContext()`. </SvelteSpecific>

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

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

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

jsx

createInertiaApp({
    withApp(app, { ssr }) {
        if (!ssr) {
            return <BrowserProvider>{app}</BrowserProvider>
        }

        return app
    },
})

createInertiaApp({
    withApp(context, { ssr }) {
        context.set('theme', 'dark')

        if (!ssr) {
            context.set('analytics', createAnalytics())
        }
    },
})

</CodeGroup>

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.

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)
    },
})

jsx

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.jsx')
        return pages[`./Pages/${name}.jsx`]()
    },
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />)
    },
})

import { createInertiaApp } from '@inertiajs/svelte'
import { mount } from 'svelte'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.svelte')
        return pages[`./Pages/${name}.svelte`]()
    },
    setup({ el, App, props }) {
        mount(App, { target: el, props })
    },
})

</CodeGroup>

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.

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

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

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

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

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

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

</CodeGroup>

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.

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",
});

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

// 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",
});

// Get a configuration value...
const duration = config.get("form.recentlySuccessfulDuration");

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

// 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",
});

// Get a configuration value...
const duration = config.get("form.recentlySuccessfulDuration");

</CodeGroup>

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.

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()

import { http } from '@inertiajs/react'

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()

import { http } from '@inertiajs/svelte'

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()

</CodeGroup>

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.