Inertia.js SSR w Laravel — konfiguracja i wdrożenie [2026]

Inertia.js domyślnie renderuje strony w przeglądarce — i to wystarcza w panelach, dashboardach i aplikacjach SaaS za logowaniem. Strony publiczne to inna historia: bez SSR pierwsze malowanie czeka na JavaScript, a Core Web Vitals cierpią. Ten przewodnik pokazuje, jak włączyć server-side rendering w aplikacji Inertia.js + Laravel — od pierwszego builda po proces produkcyjny, który przeżyje każdy deploy.

Jeśli dopiero wybierasz architekturę, zacznij od Inertia.js z Laravel i React — SPA bez osobnego API.

Kiedy SSR się opłaca (a kiedy nie)

SSR dokłada do stacku drugi runtime: proces Node, który renderuje React do HTML przy każdym żądaniu. To realna infrastruktura — opłaca się, gdy:

• Strony publiczne muszą mieć szybkie LCP — landing page, cennik, katalogi, blog.
• Treść ma być widoczna dla robotów bez wykonywania JavaScriptu.
• Podglądy społecznościowe muszą pokazywać wyrenderowaną treść, nie pustą skorupę.

Pomiń SSR, gdy wszystko jest za logowaniem. Dashboard renderowany po stronie klienta w 300 ms jest lepszym doświadczeniem niż dashboard czekający na rundę do Node. Nasza zasada: SSR dla ruchu publicznego, zwykły render kliencki dla aplikacji za autoryzacją — Inertia pozwala mieszać oba podejścia w jednym kodzie.

Jak działa SSR w Inertia.js

Przy każdym żądaniu Laravel buduje obiekt strony (nazwa komponentu + propsy), wysyła go do serwera SSR i dostaje z powrotem HTML. Ten HTML trafia do odpowiedzi, więc przeglądarka maluje od razu, a React przejmuje kontrolę po hydratacji.

Konfiguracja krok po kroku

Wpis SSR to drugi punkt wejścia React, który renderuje do stringa zamiast montować do DOM

// resources/js/ssr.jsx
import { createInertiaApp } from '@inertiajs/react';
import createServer from '@inertiajs/react/server';
import ReactDOMServer from 'react-dom/server';

createServer((page) =>
    createInertiaApp({
        page,
        render: ReactDOMServer.renderToString,
        resolve: (name) => {
            const pages = import.meta.glob('./Pages/**/*.jsx', { eager: true });
            return pages[`./Pages/${name}.jsx`];
        },
        setup: ({ App, props }) => <App {...props} />,
    })
);

Vite musi wiedzieć o drugim wpisie i zbudować go pod Node

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

Dodaj build SSR do skryptów, żeby deploy nigdy nie wysłał starego bundla

"scripts": {
    "build": "vite build && vite build --ssr"
}

Potem włącz SSR w konfiguracji Inertii i uruchom serwer renderujący lokalnie

// config/inertia.php
'ssr' => [
    'enabled' => true,
    'url' => 'http://127.0.0.1:13714',
],

php artisan inertia:start-ssr

Zobacz źródło strony w przeglądarce — powinien przyjść pełny HTML.

Wdrożenie serwera renderującego

Na VPS proces SSR trzeba nadzorować jak php-fpm: musi wstać po awarii i przy każdym wdrożeniu (trzyma zbudowany bundle w pamięci). U nas działa pod PM2 obok workerów kolejek:

pm2 start "php artisan inertia:start-ssr" --name inertia-ssr --max-memory-restart 512M
pm2 save

Kolejność wdrożenia ma znaczenie: zbuduj assety, zrestartuj inertia-ssr, potem przeładuj php-fpm. Gdy serwer SSR nie działa, Inertia zgłasza wyjątek zamiast cicho degradować — to zaleta, ale wymaga monitoringu. Alertujemy na proces, nie tylko na błędy 500.

Uwaga: API przeglądarki (window, document, localStorage) nie istnieje w procesie SSR. Zabezpiecz je w useEffect albo renderuj tylko po stronie klienta — inaczej serwer renderujący wywali się przy pierwszym żądaniu takiej strony.

Co zmienia się w komponentach

• Przenieś pobieranie danych do kontrolerów Laravel — przy SSR serwer i tak potrzebuje wszystkiego od razu.

• Unikaj losowych wartości i Date.now() w renderze; markup musi być zgodny między serwerem i klientem, inaczej hydratacja zgłasza ostrzeżenia.

• Używaj deferred props dla ciężkich danych — strona leci szybko, widgety dopełniają się po hydratacji.

• Pogłęb temat: Inertia.js v2 — deferred props i prefetching oraz testowanie aplikacji Inertia.js.

FAQ

Czy Inertia.js wymaga SSR?

Nie — działa bez SSR, a Google indeksuje strony renderowane po stronie klienta. SSR jest dla stron publicznych, gdzie liczy się szybkość pierwszego renderu i pewność indeksacji.

Czy SSR zmienia autoryzację w Laravel?

Nie. Sesje, middleware i polityki działają bez zmian — SSR tylko wstępnie renderuje stronę React do HTML.

Ile kosztuje dodanie SSR?

• Zwykle 1–3 dni: wpis SSR, pipeline buildów, nadzór procesu i poprawki kodu korzystającego z API przeglądarki.

👉 Planujesz publiczną aplikację na Inertia.js? Zobacz naszą usługę tworzenie aplikacji Laravel albo programista Laravel na zlecenie — SSR wdrażamy standardowo w projektach publicznych.

📖 Czytaj dalej: Inertia.js v2 — nowości, Inertia.js czy Livewire i Inertia.js z Laravel i React.