Skip to content
Inertia.js Documentation

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:

Terminal window
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

Before installing Inertia, you need your client-side framework and its corresponding Vite plugin installed and configured. You may skip this section if your application already has these set up.

Terminal window
npm install vue @vitejs/plugin-vue

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

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 corresponding to your framework of choice.

    Terminal window
    npm install @inertiajs/vue3

  2. Initialize the Inertia app

    Next, update your main JavaScript file to boot your Inertia app. To accomplish this, we’ll initialize the client-side framework with the base Inertia component.

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

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

    The setup callback receives everything necessary to initialize the client-side framework, including the root Inertia App component.

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

Resolving Components

The resolve callback tells Inertia how to load a page component. It receives a page name (string), and returns a page component module. How you implement this callback depends on which bundler (Vite or Webpack) you’re using.

// Vite
resolve: name => {
    const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
    return pages[`./Pages/${name}.vue`]
},


// Webpack
resolve: name => require(`./Pages/${name}`),

By default we recommend eager loading your components, which will result in a single JavaScript bundle. However, if you’d like to lazy-load your components, 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')),

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.

Script Element for Page Data

By default, Inertia stores the initial page data in a data-page attribute on the root element. You may configure Inertia to use a <script type="application/json"> element instead, which is slightly faster and easier to inspect in your browser’s dev tools.

createInertiaApp({
    // ...
    defaults: {
        future: {
            useScriptElementForInitialPage: true,
        },
    },
})

Be sure to also update your SSR entry point if you’re using server-side rendering. Laravel users should also set the inertia.use_script_element_for_initial_page config value to true so the @inertia Blade directive outputs a script element.