Upgrade guide for v1.0

What's new

Inertia.js v1.0 focuses on simplifying the overall architecture of the project with the goal of making Inertia easier to maintain and easier to use.

It includes a number of breaking changes, mostly related to package names and updated named exports. This guide explains how to upgrade your project to v1.0.

For a complete list of all the changes, see the release notes.

New dependencies

To use previous Inertia releases, you had to install a number of libraries, including the core library (@inertiajs/inertia), the adapter of your choice (@inertiajs/inertia-vue|vue3|react|svelte), the progress library (@inertiajs/progress), and if you were using server-side rendering, the server library (@inertiajs/server).

Moving forward you are now only required to install a single library — the adapter of your choice (Vue, React, or Svelte), and all other core libraries are automatically installed for you.

To get started, remove all of the old Inertia libraries.

npm remove @inertiajs/inertia @inertiajs/inertia-vue3 @inertiajs/progress @inertiajs/server

Next, install the new Inertia adapter of your choice. The new adapter libraries have been renamed, and no longer include inertia- in them.

npm install @inertiajs/vue3

Renamed imports

Next, update all the Inertia related imports in your project to use the new adapter library name. All imports are now available from the adapter library, meaning you no longer import anything from the Inertia core library, progress library, or server library.

Additionally, some exports have been renamed and previously deprecated exports have been removed. For example, the Inertia export has been renamed to router.

Here is a complete list of all the import changes:

- import { Inertia } from '@inertiajs/inertia'
+ import { router } from '@inertiajs/vue3'

- import createServer from '@inertiajs/server'
+ import createServer from '@inertiajs/vue3/server'

- import { createInertiaApp } from '@inertiajs/inertia-vue3'
- import { App } from '@inertiajs/inertia-vue3'
- import { app } from '@inertiajs/inertia-vue3'
- import { plugin } from '@inertiajs/inertia-vue3'
- import { InertiaApp } from '@inertiajs/inertia-vue3'
+ import { createInertiaApp } from '@inertiajs/vue3'

- import { usePage } from '@inertiajs/inertia-vue3'
+ import { usePage } from '@inertiajs/vue3'

- import { useForm } from '@inertiajs/inertia-vue3'
+ import { useForm } from '@inertiajs/vue3'

- import { useRemember } from '@inertiajs/inertia-vue3'
+ import { useRemember } from '@inertiajs/vue3'

- import { Head } from '@inertiajs/inertia-vue3'
- import { InertiaHead } from '@inertiajs/inertia-vue3'
+ import { Head } from '@inertiajs/vue3'

- import { Link } from '@inertiajs/inertia-vue3'
- import { link } from '@inertiajs/inertia-vue3'
- import { InertiaLink } from '@inertiajs/inertia-vue3'
+ import { Link } from '@inertiajs/vue3'

Progress

Previously, the progress indicator was available as a separate plugin (@inertiajs/progress). It is now installed and enabled by default.

If you haven't yet, remove the old progress library.

npm remove @inertiajs/progress

Next, remove the InertiaProgress import and InertiaProgress.init() call, as they are no longer required.

- import { InertiaProgress } from '@inertiajs/progress'

- InertiaProgress.init()

Finally, if you have defined any progress customizations, you can move them to the progress property of the createInertiaApp() helper.

createInertiaApp({
  progress: {
    color: '#29d',
  },
  // ...
})

If you're using a custom progress indicator, you can disable the default progress indicator by setting the progress property to false.

createInertiaApp({
  progress: false,
  // ...
})

Setup arguments

We've removed the previously deprecated lowercase app argument from the setup() method in createInertiaApp(). Use App instead.

  createInertiaApp({
    // ...
-   setup({ app, props }) {
+   setup({ App, props }) {
      // ...
    },
  })

Simplified usePage

In the Vue 3 adapter, we simplified the usePage() hook to no longer require adding .value after the component, props, url and version properties.

If you're using the usePage() hook, remove all instances of .value.

  import { computed } from 'vue'

- const appName = computed(() => usePage().props.value.appName)
+ const appName = computed(() => usePage().props.appName)