Inertia.js i TypeScript — konfiguracja i typowanie [2026]

Inertia.js przekazuje dane z Laravela do Reacta jako propsy strony — i w czystym JavaScripcie nic nie weryfikuje, że propsy, których oczekuje komponent, to propsy, które wysyła kontroler. TypeScript zamyka tę lukę: kontrakt propsów staje się jawny, refaktory przestają straszyć, a edytor podpowiada propsy jak wszystko inne. Oto konfiguracja, której używamy.

Jeśli Inertia jest dla Ciebie nowa: Inertia.js z Laravel i React — SPA bez osobnego API.

Kontrakt PageProps

Zacznij od jednego źródła prawdy dla propsów strony

// resources/js/types/inertia.d.ts
import '@inertiajs/core';

export interface SharedProps {
    auth: {
        user: { id: number; name: string; email: string } | null;
    };
    flash: { success?: string; error?: string };
    [key: string]: unknown;
}

declare module '@inertiajs/core' {
    interface PageProps extends SharedProps {}
}

Każda strona deklaruje własne propsy

// resources/js/Pages/Orders/Index.tsx
import { Head } from '@inertiajs/react';
import type { SharedProps } from '@/types/inertia';

interface Order {
    id: number;
    number: string;
    total: number;
    status: 'new' | 'paid' | 'shipped';
}

interface Props extends SharedProps {
    orders: { data: Order[]; links: { url: string | null; label: string }[] };
    filters: { status?: string; search?: string };
}

export default function OrdersIndex({ orders, filters, auth }: Props) {
    return (
        <>
            <Head title="Zamówienia" />
            <h1>Zamówienia użytkownika {auth.user?.name}</h1>
            {/* ... */}
        </>
    );
}

Strona Laravela nie wymaga adnotacji — ale resource jest naturalnym miejscem dokumentującym payload

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'number' => $this->number,
            'total' => (float) $this->total,
            'status' => $this->status,
        ];
    }
}

Wskazówka: Trzymaj interfejsy propsów obok komponentu strony, nie w globalnym katalogu typów. Kontrakt należy do strony — kolokacja sprawia, że rozjazd widać w code review.

Typowanie useForm

useForm przyjmuje generyk — przekaż kształt danych formularza

interface CreateOrderForm {
    customer_id: number | '';
    note: string;
}

const { data, setData, post, errors } = useForm<CreateOrderForm>({
    customer_id: '',
    note: '',
});

Teraz setData('custmer_id', ...) to błąd kompilacji, a errors jest kluczowane nazwami twoich pól. Analogicznie usePage<SharedProps>() przy czytaniu danych współdzielonych poza komponentem strony.

Generowanie typów z Laravela

Ręczne utrzymywanie bliźniaków TS dla enumów i value objects szybko się nudzi. Generujemy je

composer require spatie/laravel-typescript-transformer
php artisan typescript:transform

Wygenerowane unie enumów i typy resource'ów lądują w resources/js/types/generated.d.ts i są commitowane — CI wywala się przy rozjeździe z PHP.

Jak utrzymać to w ryzach

npm run typecheck   # tsc --noEmit

Trzy nawyki sprawiają, że typowanie się zwraca

• Strict mode. "strict": true w tsconfig — inaczej połowa wartości paruje.
• Typecheck w CI. Padający tsc --noEmit blokuje build; rozjazd propsów nie trafia na produkcję.
• Typuj szew, nie wszystko. Propsy stron, shared props, dane formularzy i API resources — granice. Wewnętrzne propsy komponentów mogą zostać lekkie.

Co to daje

W kodzie Inertii błędy mieszkają na szwie propsów: kontroler zmienia nazwę klucza, resource zmienia kształt, strona po cichu renderuje undefined. TypeScript zamienia je w czerwone podkreślenia przy commicie. W połączeniu z wzorcami walidacji formularzy i testami daje setup, w którym kompilator i testy łapią to, co umyka code review.

Typowane stacki Inertia konfigurujemy domyślnie w nowych projektach — zobacz tworzenie aplikacji Laravel.

FAQ

Czy typy można generować z Laravela?

Tak — spatie/laravel-typescript-transformer i podobne generują definicje TS z resource'ów i enumów. Generujemy enumy i typy payloadów; interfejsy propsów piszemy ręcznie.

Czy TypeScript spowalnia development?

Konfiguracja to popołudnie; potem typowanie propsów eliminuje najczęstszy błąd — komponent czyta nieistniejący prop.

Czy opłaca się w małym projekcie?

Jeśli ma więcej niż kilka stron i przeżyje prototyp — tak. Koszt jednorazowy, korzyść narasta.

👉 Chcesz typowany, bezpieczny w refaktorach kod Inertia.js? Zobacz tworzenie aplikacji Laravel albo programista Laravel na zlecenie.

📖 Czytaj dalej: Inertia.js z Laravel i React, formularze i walidacja w Inertia.js i testowanie aplikacji Inertia.js.