Inertia.js v3 — co nowego i jak zaktualizować [2026]

Inertia.js v3 to duże wydanie skupione na prostocie i doświadczeniu dewelopera. Usuwa Axiosa, dodaje plugin Vite, który automatycznie rozwiązuje strony i konfiguruje SSR, wprowadza samodzielne żądania HTTP przez useHttp, optymistyczne aktualizacje, instant visits i layout props. Jeśli zaczynasz nowy projekt Laravel + React w 2026 roku, v3 jest domyślnym wyborem. Jeśli aktualizujesz z v2, ten przewodnik prowadzi przez zmiany w kolejności, w której warto je zastosować.

Najważniejsze: W skrócie — v3 wymaga PHP 8.2+, Laravel 11+ i React 19+. Zastąp Axiosa wbudowanym klientem HTTP, przenieś rozwiązywanie stron do @inertiajs/vite, opublikuj ponownie konfigurację Inertii, zaktualizuj główny widok Blade i przetestuj SSR, formularze oraz layouty. Większość aplikacji potrzebuje kilku godzin, nie przepisania.

Co nowego w Inertia.js v3?

Plugin Vite

W v2 każda aplikacja powtarzała ten sam boilerplate: callback resolve do mapowania nazw stron na komponenty, callback setup do montowania aplikacji i osobny entry SSR. Nowy plugin @inertiajs/vite obsługuje to wszystko. Dodaj plugin do vite.config.js i wywołaj createInertiaApp() bez argumentów:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import inertia from '@inertiajs/vite';
import react from '@vitejs/plugin-react';

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

import { createInertiaApp } from '@inertiajs/react';

createInertiaApp();

Plugin rozwiązuje strony z ./Pages, obsługuje lazy loading i code splitting oraz konfiguruje SSR. Callbacki setup i resolve są teraz opcjonalne — zostaw je tylko wtedy, gdy potrzebujesz własnego zachowania.

SSR w development bez osobnego serwera

W v2 SSR w development oznaczał zbudowanie bundle'a SSR i uruchomienie osobnego procesu Node. Z pluginem Vite SSR działa automatycznie podczas developmentu: uruchamiasz npm run dev i strony są renderowane na serwerze. Produkcyjny workflow się nie zmienia — budujesz bundle klienta i SSR oraz uruchamiasz serwer SSR.

Usunięty Axios

Inertia nie zawiera już Axiosa i nie zależy od niego. Wbudowany klient XHR obsługuje wewnętrzną komunikację HTTP, co zmniejsza bundle i usuwa zależność. Pakiet qs również zniknął. Jeśli używasz interceptorów Axiosa, przenieś je do wbudowanych interceptorów albo zachowaj Axiosa przez adapter.

useHttp do samodzielnych żądań

Nie każde żądanie powinno wywoływać page visit. Wyszukiwanie, wywołania API i zewnętrzne usługi potrzebują zwykłego HTTP bez cyklu życia Inertii. Hook useHttp daje ten sam reaktywny stan, obsługę błędów, postęp uploadu i anulowanie co useForm:

import { useHttp } from '@inertiajs/react';

const { data, setData, get, processing, errors } = useHttp({
    query: '',
});

function search() {
    get('/api/search', {
        onSuccess: (response) => console.log(response),
    });
}

Optimistic updates

Wywołaj optimistic() przed router visit, żeby zastosować zmianę natychmiast i automatycznie ją wycofać, jeśli serwer ją odrzuci:

router.optimistic((props) => ({
    likes: props.likes + 1,
})).post(`/posts/${post.id}/like`);

Optymistyczne aktualizacje działają z router visits, komponentem <Form>, useForm i useHttp. Wiele równoległych aktualizacji jest śledzonych niezależnie.

Instant visits

Instant visits podmieniają docelowy komponent od razu, a żądanie do serwera leci w tle. Użytkownik widzi nową stronę natychmiast ze współdzielonymi propsami; dane specyficzne dla strony dokładają się po odpowiedzi serwera.

Layout props

Trwałe layouty przetrwają nawigację, ale dzielenie dynamicznych danych z layoutem wymagało event busa albo provide/inject. useLayoutProps i setLayoutProps rozwiązują ten problem:

const { title } = useLayoutProps();

setLayoutProps({ title: 'Orders' });

Nazwane layouty, zagnieżdżone layouty i statyczne propsy są wspierane. Możesz też ustawić domyślny layout w createInertiaApp.

Obsługa wyjątków

Błędy takie jak 404 mogą wystąpić poza middleware Inertii, gdzie współdzielone dane i główny widok nie są dostępne. handleExceptionsUsing() pozwala wyrenderować własną stronę błędu Inertii ze współdzielonymi propsami:

use Inertia\Inertia;

Inertia::handleExceptionsUsing(function ($e) {
    return Inertia::render('Error', [
        'status' => $e->getStatusCode(),
    ])->withSharedData();
});

Zwrócenie null wraca do domyślnego renderowania wyjątków Laravela.

Mniejsze usprawnienia

• Zagnieżdżone typy propsów: Inertia::optional(), Inertia::defer() i Inertia::merge() działają w zagnieżdżonych tablicach, z dot-notation w partial reloads.
• Zmiany nazw zdarzeń: invalid → httpException, exception → networkError, plus per-visit onHttpException i onNetworkError.
• Domyślny layout w createInertiaApp.
• Generyki TypeScript dla komponentu <Form>.
• Enumy PHP w Inertia::render().
• preserveErrors dla partial reloads.
• Pakiety tylko ESM.

Wymagania

Jeśli jesteś na React 18, zostań na Inertia v2 do czasu aktualizacji Reacta. Jeśli jesteś na Laravel 10 lub PHP 8.1, najpierw zaktualizuj platformę — v3 się nie zainstaluje.

Aktualizacja krok po kroku

1. Zaktualizuj zależności

npm install @inertiajs/react@^3.0
npm install @inertiajs/vite@^3.0
composer require inertiajs/inertia-laravel:^3.0

Jeśli używasz Vue lub Svelte, zainstaluj odpowiedni adapter (@inertiajs/vue3@^3.0 lub @inertiajs/svelte@^3.0).

2. Opublikuj konfigurację ponownie

Plik konfiguracyjny Laravela został przebudowany. Opublikuj go ponownie i przenieś customizacje

php artisan vendor:publish --provider="Inertia\ServiceProvider" --force
php artisan view:clear

3. Zaktualizuj główny widok Blade

Atrybut inertia w <head> to teraz data-inertia

<title data-inertia>{{ config('app.name') }}</title>

Możesz też użyć nowych komponentów Blade

<head>
    @vite('resources/js/app.jsx')
    <x-inertia::head>
        <title>{{ config('app.name') }}</title>
    </x-inertia::head>
</head>
<body>
    <x-inertia::app />
</body>

4. Dodaj plugin Vite

Dodaj @inertiajs/vite do vite.config.js i uprość resources/js/app.jsx

import inertia from '@inertiajs/vite';

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

import { createInertiaApp } from '@inertiajs/react';

createInertiaApp();

Zostaw jawny callback resolve, jeśli strony mieszkają poza resources/js/Pages albo potrzebują własnego rozwiązywania.

5. Zastąp Axiosa

Wyszukaj importy axios w froncie

rg "axios" resources/js

Zastąp wewnętrzne interceptory wbudowanym klientem

import { router } from '@inertiajs/react';

router.on('httpException', (event) => {
    // obsłuż 4xx/5xx
});

Do samodzielnych żądań używaj useHttp lub fetch. Jeśli musisz zachować Axiosa, zainstaluj adapter i postępuj zgodnie z dokumentacją.

6. Napraw zmiany łamiące zgodność

• Inertia::lazy() jest usunięte — użyj Inertia::optional().
• router.cancel() to teraz router.cancelAll().
• Blok konfiguracji future jest usunięty; wszystkie flagi future z v2 są zawsze włączone.
• Eksporty hideProgress() i revealProgress() są usunięte — użyj obiektu progress.
• Layouty React jako arrow function muszą być opakowane w tablicę: Page.layout = [Layout].
• Stan przetwarzania formularza resetuje się w onFinish, a nie od razu po odpowiedzi.
• Początkowe dane strony są zawsze przekazywane przez <script type="application/json">; stary atrybut data-page zniknął.
• Właściwości clearHistory i encryptHistory są dołączane tylko wtedy, gdy są true.

7. Przetestuj aktualizację

Uruchom pełny zestaw testów i sprawdź ręcznie krytyczne ścieżki

php artisan test
npm run build
npm run build:ssr

Przetestuj

• logowanie, wylogowanie i rejestrację;
• formularze z błędami walidacji i uploadem plików;
• nawigację z preserveScroll i preserveState;
• partial reloads i deferred props;
• output SSR (źródło strony, nie tylko wyrenderowany DOM);
• build produkcyjny, nie tylko dev server.

Uwaga: Najczęstsza przyczyna nieudanej aktualizacji to nieaktualny plik konfiguracyjny. Jeśli strony się nie rozwiązują albo SSR nie startuje, opublikuj ponownie config/inertia.php, wyczyść cache widoków i zrestartuj proces SSR, zanim zaczniesz debugować cokolwiek innego.

Czy aktualizować teraz?

Aktualizuj, jeśli

• zaczynasz nowy projekt;
• jesteś na Laravel 11+ i React 19+;
• chcesz plugin Vite, useHttp lub optimistic updates;
• planujesz odświeżenie frontendu.

Poczekaj, jeśli

• jesteś na React 18 i nie możesz go teraz zaktualizować;
• jesteś na Laravel 10 lub PHP 8.1;
• jesteś w środku freeze'u wydawniczego.

Aktualizacja nie jest pilna dla stabilnej aplikacji na v2, ale v3 jest długoterminową ścieżką. Zaplanuj ją jako skupiony sprint, nie zadanie w tle.

FAQ

Czy Inertia.js v3 jest stabilna?

Tak. v3 jest wydane i udokumentowane, z oficjalnym przewodnikiem aktualizacji. Po aktualizacji przetestuj SSR i formularze — to obszary najbardziej narażone na problemy.

Czy muszę używać pluginu Vite?

Nie. Usuwa boilerplate i upraszcza SSR, ale jawne callbacki resolve i setup nadal działają. Używaj pluginu, chyba że masz własną strategię rozwiązywania stron.

Czy mogę zachować Axiosa?

Tak, przez adapter Axiosa. Większość aplikacji go nie potrzebuje — wbudowany klient obsługuje interceptory i upload plików.

Czy v3 wspiera React 18?

Nie. Adapter React wymaga React 19+. Najpierw zaktualizuj Reacta albo zostań na v2.

Co stało się z Inertia::lazy()?

Zostało usunięte. Zastąp je Inertia::optional(), które daje to samo zachowanie.

Czy SSR jest wymagane?

Nie, ale jest zalecane dla publicznych stron. v3 ułatwia SSR w development i zachowuje podobny workflow produkcyjny.

Ile trwa aktualizacja?

Typowa aplikacja Laravel + React zajmuje kilka godzin do jednego dnia, łącznie z testami. Duże aplikacje z własnym rozwiązywaniem stron i dużym użyciem Axiosa potrzebują więcej czasu.

Źródła

• Przewodnik aktualizacji do Inertia.js v3
• Dokumentacja Inertia.js v3
• Zapowiedź Inertia.js v3
• Dokumentacja Laravela
• Dokumentacja React 19

Potrzebujesz pomocy przy aktualizacji produkcyjnej aplikacji Inertia.js? Sprawdź nasze usługi Laravel development albo zatrudnij programistę Laravel.

Czytaj dalej: Inertia.js z Laravel i React, Inertia.js SSR w Laravel, Inertia.js czy Livewire i Inertia.js czy Next.js.