Server-Side Rendering (SSR)

Server-side rendering render trước các trang JavaScript trên máy chủ, nhờ đó người truy cập nhận được HTML đã được render đầy đủ khi truy cập ứng dụng. Vì ứng dụng phục vụ HTML hoàn chỉnh, các công cụ tìm kiếm cũng dễ index website hơn. Server-side rendering dùng Node.js để render page trong background process; do đó server phải có Node để SSR hoạt động đúng. SSR server của Inertia yêu cầu Node.js 22 trở lên.

Laravel Starter Kit

Nếu đang dùng Laravel Starter Kits, Inertia SSR được hỗ trợ thông qua một build command:

npm run build:ssr

Thiết lập Vite Plugin

Cách được khuyến nghị để cấu hình SSR là dùng @inertiajs/vite plugin. Cách này tự động xử lý cấu hình SSR, bao gồm SSR ở development mode mà không cần Node.js server riêng.

Install the Vite plugin

npm install @inertiajs/vite

Configure Vite

Thêm Inertia plugin vào file vite.config.js. Plugin tự động phát hiện SSR entry point.

vite.config.js

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

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

Bạn cũng có thể cấu hình SSR option rõ ràng.

vite.config.js

inertia({
    ssr: {
        entry: 'resources/js/ssr.js',
        port: 13714,
        host: '127.0.0.1',
        cluster: true,
    },
})

Bạn có thể truyền false để tắt xử lý SSR tự động của plugin, ví dụ khi muốn cấu hình SSR thủ công hoặc tắt hoàn toàn SSR.

vite.config.js

inertia({
    ssr: false,
})

Update your build script

Cập nhật script build trong package.json để build cả hai bundle.

package.json

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

Development mode

Vite plugin tự động xử lý SSR trong development. Không cần build SSR bundle hay chạy Node.js server riêng. Chỉ cần chạy Vite dev server như bình thường:

npm run dev

Vite plugin expose server endpoint để Laravel dùng cho rendering, có đầy đủ hỗ trợ HMR.

Production

Trong production, build cả hai bundle rồi khởi động SSR server.

npm run build
php artisan inertia:start-ssr

Clustering

Mặc định SSR server chạy một thread. Bạn có thể bật clustering để chạy nhiều Node server trên cùng port, request được xử lý bởi từng thread theo round-robin.

vite.config.js

inertia({
    ssr: {
        cluster: true,
    },
})

Host

Mặc định SSR server bind 0.0.0.0, nên truy cập được từ mọi network interface. Bạn có thể giới hạn vào interface cụ thể bằng tùy chọn host.

vite.config.js

inertia({
    ssr: {
        host: '127.0.0.1',
    },
})

Thiết lập thủ công

Vite plugin mặc định tái sử dụng entry point app.js cho SSR nên không cần file riêng. Hầu hết tùy chỉnh có thể xử lý bằng withApp callback. Để kiểm soát nhiều hơn, chẳng hạn cung cấp callback setup thủ công, bạn có thể tạo entry point resources/js/ssr.js riêng và cập nhật app.js để dùng client-side hydration.

SSR Entry Point

import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'

createServer(page =>
    createInertiaApp({
        page,
        render: renderToString,
        resolve: name => {
            const pages = import.meta.glob('./Pages/**/*.vue')
            return pages[`./Pages/${name}.vue`]()
        },
        setup({ App, props, plugin }) {
            return createSSRApp({
                render: () => h(App, props),
            }).use(plugin)
        },
    }),
)

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')
            return pages[`./Pages/${name}.jsx`]()
        },
        setup: ({ App, props }) => <App {...props} />,
    }),
)

import { createInertiaApp } from '@inertiajs/svelte'
import createServer from '@inertiajs/svelte/server'
import { render } from 'svelte/server'

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

Hãy thêm vào app.js bất kỳ phần nào còn thiếu nhưng hợp lý khi chạy SSR, chẳng hạn plugin hoặc custom mixin.

Client-side hydration

import { createApp, h } from 'vue'
import { createSSRApp, 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) }) 
    createSSRApp({ render: () => h(App, props) }) 
        .use(plugin)
        .mount(el)
    },
})

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'
import { hydrateRoot } from 'react-dom/client'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.jsx')
        return pages[`./Pages/${name}.jsx`]()
    },
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />) 
        hydrateRoot(el, <App {...props} />) 
    },
})

import { createInertiaApp } from '@inertiajs/svelte'
import { mount } from 'svelte'
import { hydrate, mount } from 'svelte'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.svelte')
        return pages[`./Pages/${name}.svelte`]()
    },
    setup({ el, App, props }) {
        mount(App, { target: el, props }) 
        if (el.dataset.serverRendered === 'true') { 
            hydrate(App, { target: el, props })
        } else {
            mount(App, { target: el, props })
        }
    },
})

Không dùng xử lý tự động của Vite Plugin

Bạn có thể truyền ssr: false cho Inertia plugin để tắt xử lý SSR tự động và tự quản lý SSR build. Bạn cũng nên thêm thuộc tính ssr vào cấu hình Laravel Vite plugin để nó biết entry point.

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            ssr: 'resources/js/ssr.js', 
            refresh: true,
        }),
        inertia({
            ssr: false, 
        }),
    ],
})

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

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            ssr: 'resources/js/ssr.js', 
            refresh: true,
        }),
        inertia({
            ssr: false, 
        }),
    ],
})

Clustering

Bạn có thể truyền tùy chọn cluster vào createServer để chạy nhiều Node server trên cùng port, request được phân phối round-robin.

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { cluster: true },
)

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { cluster: true },
)

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { cluster: true },
)

Host

Mặc định SSR server bind 0.0.0.0, truy cập được từ mọi interface. Bạn có thể truyền tùy chọn host vào createServer để giới hạn vào interface cụ thể.

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { host: '127.0.0.1' },
)

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { host: '127.0.0.1' },
)

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { host: '127.0.0.1' },
)

Chạy SSR server

SSR server chỉ bắt buộc trong production. Trong development, Vite plugin tự động xử lý SSR.

Sau khi build cả client-side và server-side bundle, bạn có thể khởi động SSR server bằng Artisan command sau.

php artisan inertia:start-ssr

Mặc định SSR server dùng node làm runtime. Bạn có thể đổi bằng tùy chọn runtime trong config/inertia.php. Path tuyệt đối tới runtime binary cũng được hỗ trợ.

'ssr' => [
    'runtime' => env('INERTIA_SSR_RUNTIME', 'node'),
],

Flag --runtime trên Artisan command override giá trị cấu hình cho một lần gọi.

php artisan inertia:start-ssr --runtime=bun

Bạn cũng có thể bật ensure_runtime_exists để kiểm tra runtime binary tồn tại trước khi khởi động SSR server. Command sẽ thoát với lỗi nếu không tìm thấy binary.

'ssr' => [
    'ensure_runtime_exists' => (bool) env('INERTIA_SSR_ENSURE_RUNTIME_EXISTS', false),
],

Khi server đang chạy, bạn có thể truy cập app trong trình duyệt với SSR đã bật. Thậm chí có thể tắt hoàn toàn JavaScript mà vẫn điều hướng được trong ứng dụng.

Xử lý lỗi

Khi SSR render thất bại, Inertia graceful fallback về client-side rendering. Vite plugin ghi thông tin lỗi chi tiết ra console, gồm component name, request URL, source location và hint phù hợp để xử lý. Các lỗi SSR phổ biến được tự động phân loại. Browser API error như tham chiếu window hoặc document trong server-rendered code đi kèm hướng dẫn chuyển code vào lifecycle hook. Component resolution error gợi ý kiểm tra file path và casing. Inertia cũng dispatch event SsrRenderFailed phía server. Bạn có thể lắng nghe event để log lỗi hoặc gửi tới error tracking service.

use Illuminate\Support\Facades\Log;
use Inertia\Ssr\SsrRenderFailed;

Event::listen(SsrRenderFailed::class, function (SsrRenderFailed $event) {
    Log::warning('SSR failed', $event->toArray());
});

Ném exception khi lỗi

Vì Inertia graceful fallback về client-side rendering, lỗi SSR có thể không được chú ý. Test vẫn pass vì client-side render thành công nhưng user không bao giờ nhận server-rendered HTML. Điều này đặc biệt phổ biến trong E2E test bằng Laravel Dusk hoặc Pest Browser Testing. Bạn có thể đặt tùy chọn throw_on_error trong config/inertia.php để ném exception thay vì fallback im lặng, giúp phát hiện vấn đề SSR sớm.

'ssr' => [
    'throw_on_error' => (bool) env('INERTIA_SSR_THROW_ON_ERROR', false),
],

Không khuyến nghị tùy chọn này trong production vì lỗi SSR sẽ trả error response thay vì fallback về client-side rendering.

Bạn có thể đặt environment variable trong phpunit.xml để chỉ bật trong testing.

<env name="INERTIA_SSR_THROW_ON_ERROR" value="true"/>

Tắt SSR

SSR có hai lớp: Vite plugin phục vụ SSR trong development và build SSR bundle cho production, còn Laravel adapter dispatch rendering request tới SSR server. Để tắt hoàn toàn SSR, nên tắt cả hai.

vite.config.js

inertia({
    ssr: false,
})

config/inertia.php

'ssr' => [
    'enabled' => false,
],

Bạn cũng có thể ngăn Laravel adapter dispatch SSR request bằng lập trình qua phương thức Inertia::disableSsr(). Điều này hữu ích khi muốn giữ SSR trong build nhưng tắt khi test hoặc trong môi trường cụ thể.

use Inertia\Inertia;

Inertia::disableSsr();

Có thể truyền boolean hoặc closure để tắt SSR theo điều kiện.

Inertia::disableSsr(app()->runningUnitTests());

Inertia::disableSsr(fn () => app()->runningUnitTests());

Loại route khỏi SSR

Đôi khi bạn muốn bỏ qua server-side rendering cho một số route trong khi vẫn bật SSR cho phần còn lại của ứng dụng.

Qua Middleware

Bạn có thể dùng property $withoutSsr trên Inertia middleware để tắt SSR cho các route pattern cụ thể.

use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    /**
     * Defines the routes that should not use SSR.
     *
     * @var array<int, string>
     */
    protected $withoutSsr = [
        'admin/*',
        'dashboard',
    ];
}

Qua Facade

Bạn cũng có thể loại các route cụ thể bằng phương thức Inertia::withoutSsr(), thường được gọi từ service provider.

use Inertia\Inertia;

Inertia::withoutSsr(['admin/*', 'dashboard']);

Theo từng request

Bạn có thể tắt SSR cho request hiện tại bằng cách đặt cấu hình inertia.ssr.enabled thành false.

if (request()->is('admin/*')) {
    config(['inertia.ssr.enabled' => false]);
}

Triển khai

Khi deploy app có SSR lên production, bạn cần build cả client-side bundle (app.js) và server-side bundle (ssr.js), sau đó chạy SSR server như background process, thường bằng process monitor như Supervisor.

php artisan inertia:start-ssr

Để dừng SSR server, chẳng hạn khi triển khai phiên bản mới của website, bạn có thể dùng Artisan command inertia:stop-ssr. Công cụ giám sát tiến trình (như Supervisor) cần chịu trách nhiệm tự động khởi động lại SSR server sau khi nó dừng.

php artisan inertia:stop-ssr

Bạn có thể dùng Artisan command inertia:check-ssr để xác minh SSR server đang chạy. Điều này hữu ích sau khi deploy và rất phù hợp làm Docker health check để đảm bảo server phản hồi đúng như mong đợi.

php artisan inertia:check-ssr

Mặc định, hệ thống sẽ kiểm tra server-side bundle tồn tại trước khi gửi request tới SSR server. Trong một số trường hợp, chẳng hạn ứng dụng chạy trên nhiều server hoặc trong container, web server có thể không truy cập được SSR bundle. Để tắt kiểm tra này, đặt giá trị cấu hình inertia.ssr.ensure_bundle_exists thành false.

Laravel Cloud

Để chạy SSR server trên Laravel Cloud, bạn có thể dùng hỗ trợ Inertia SSR nguyên bản của Cloud.

Laravel Forge

Để chạy SSR server trên Forge, bạn có thể bật nó bằng tùy chọn Inertia SSR trong panel ứng dụng của site. Forge sẽ tạo daemon cần thiết và, nếu bạn chọn, cập nhật deploy script để khởi động lại SSR server sau mỗi lần deploy.

Tài liệu chính thức

Bài dịch này được đối chiếu từ tài liệu Inertia.js v3 chính thức. Nếu có khác biệt do phiên bản hoặc cập nhật mới, hãy ưu tiên tài liệu chính thức làm nguồn tham chiếu.

Bắt đầu

Cài đặt

Khái niệm cốt lõi

Kiến thức cơ bản

Dữ liệu & Props

Bảo mật

Nâng cao

Laravel Starter Kit

Thiết lập Vite Plugin

Development mode

Production

Clustering

Host

Thiết lập thủ công

SSR Entry Point

Client-side hydration

Không dùng xử lý tự động của Vite Plugin

Clustering

Host

Chạy SSR server

Xử lý lỗi

Ném exception khi lỗi

Tắt SSR

Loại route khỏi SSR

Qua Middleware

Qua Facade

Theo từng request

Triển khai

Laravel Cloud

Laravel Forge

Tài liệu chính thức

​Laravel Starter Kit

​Thiết lập Vite Plugin

​Development mode

​Production

​Clustering

​Host

​Thiết lập thủ công

​SSR Entry Point

​Client-side hydration

​Không dùng xử lý tự động của Vite Plugin

​Clustering

​Host

​Chạy SSR server

​Xử lý lỗi

​Ném exception khi lỗi

​Tắt SSR

​Loại route khỏi SSR

​Qua Middleware

​Qua Facade

​Theo từng request

​Triển khai

​Laravel Cloud

​Laravel Forge

​Tài liệu chính thức

Laravel Starter Kit

Thiết lập Vite Plugin

Development mode

Production

Clustering

Host

Thiết lập thủ công

SSR Entry Point

Client-side hydration

Không dùng xử lý tự động của Vite Plugin

Clustering

Host

Chạy SSR server

Xử lý lỗi

Ném exception khi lỗi

Tắt SSR

Loại route khỏi SSR

Qua Middleware

Qua Facade

Theo từng request

Triển khai

Laravel Cloud

Laravel Forge

Tài liệu chính thức