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.
Prerequisites
NOTE
You can skip this step if you have already executed the Rails generator.
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.
npm install vue @vitejs/plugin-vueThen, add the framework plugin to your vite.config.js file.
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [RubyPlugin(), vue()],
})For more information on configuring these plugins, consult Vite Rails documentation.
Installation
NOTE
You can skip this step if you have already executed the Rails generator.
Install dependencies
Install the Inertia client-side adapter and Vite plugin.
NOTE
The @inertiajs/vite plugin supports Vite 7 and Vite 8.
npm install @inertiajs/vue3 @inertiajs/viteConfigure Vite
Add the Inertia plugin to your vite.config.js file.
import inertia from '@inertiajs/vite'
import RubyPlugin from 'vite-plugin-ruby'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
RubyPlugin(),
inertia(),
// ...
],
})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.
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.
import { createInertiaApp } from '@inertiajs/vue3'
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.
import { createInertiaApp } from '@inertiajs/vue3'
import { createI18n } from 'vue-i18n'
const i18n = createI18n({
// ...
})
createInertiaApp({
withApp(app) {
app.use(i18n)
},
})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)
}
},
})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.
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.
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',
})
// Get a configuration value...
const duration = config.get('form.recentlySuccessfulDuration')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()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.