Server-Side Rendering (SSR)

Bạn đang xem tài liệu Inertia.js v2. Inertia.js v3 đã được phát hành và hiện là phiên bản mặc định. Hãy xem hướng dẫn nâng cấp để bắt đầu.

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 sử dụng Node.js để render trang trong một tiến trình nền; vì vậy Node phải có sẵn trên máy chủ để SSR hoạt động đúng.

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

Thêm entry point phía máy chủ

Để cấu hình SSR thủ công mà không dùng Laravel starter kit, trước tiên hãy tạo file entry point SSR trong project Laravel.

touch resources/js/ssr.js

touch resources/js/ssr.jsx

touch resources/js/ssr.js

File này sẽ rất giống entry point của ứng dụng, ngoại trừ việc nó không chạy trong trình duyệt mà chạy trong Node.js. Dưới đây là ví dụ hoàn chỉnh.

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

createServer(page =>
    createInertiaApp({
        page,
        render: renderToString,
        resolve: name => {
            const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
            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', { eager: true })
            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', { eager: true })
            return pages[`./Pages/${name}.svelte`]
        },
        setup({ App, props }) {
            return render(App, { props })
        },
    }),
)

Khi tạo file này, hãy nhớ bổ sung mọi phần còn thiếu so với app.js nhưng phù hợp để chạy ở chế độ SSR, chẳng hạn plugin hoặc custom mixin.

Clustering

Mặc định, SSR server chạy trên một thread duy nhất. Clustering khởi động nhiều Node server trên cùng một port, sau đó request được phân phối cho từng thread theo cơ chế round-robin. Bạn có thể bật clustering bằng cách truyền một đối số options thứ hai vào createServer.

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

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

import { createInertiaApp } from '@inertiajs/react'
import createServer from '@inertiajs/react/server'
import ReactDOMServer from 'react-dom/server'

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

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

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

Hydration phía client

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', { eager: true })
        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', { eager: true })
        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', { eager: true })
        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 })
        }
    },
})

Thiết lập Vite

Tiếp theo, cập nhật cấu hình Vite để build entry point SSR mới bằng cách thêm thuộc tính ssr vào cấu hình plugin Vite của Laravel trong file vite.config.js.

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

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

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

Cập nhật NPM script

Tiếp theo, cập nhật script build trong file package.json để build cả entry point SSR.

package.json

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

Giờ bạn có thể build cả bundle phía client và phía máy chủ.

npm run build

Chạy SSR server

Sau khi đã build cả bundle phía client và phía máy chủ, bạn có thể chạy Inertia SSR server dựa trên Node bằng command sau.

php artisan inertia:start-ssr

Bạn có thể dùng tùy chọn --runtime để chỉ định runtime muốn sử dụng. Điều này cho phép chuyển từ runtime Node.js mặc định sang Bun.

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

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

Tắt SSR

Đôi khi bạn có thể muốn tắt server-side rendering cho một số trang hoặc route nhất định trong ứng dụng. Bạn có thể làm vậy bằng cách đặt giá trị cấu hình inertia.ssr.enabled thành false cho request hiện tại, thường trong service provider hoặc middleware.

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

Triển khai

Khi triển khai ứng dụng có SSR lên production, bạn cần build cả bundle phía client (app.js) và phía máy chủ (ssr.js), sau đó chạy SSR server như một background process, thường thông qua công cụ giám sát tiến trình 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 v2 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

Thêm entry point phía máy chủ

Clustering

Hydration phía client

Thiết lập Vite

Cập nhật NPM script

Chạy SSR server

Tắt SSR

Triển khai

Laravel Cloud

Laravel Forge

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

​Laravel Starter Kit

​Thêm entry point phía máy chủ

​Clustering

​Hydration phía client

​Thiết lập Vite

​Cập nhật NPM script

​Chạy SSR server

​Tắt SSR

​Triển khai

​Laravel Cloud

​Laravel Forge

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

Laravel Starter Kit

Thêm entry point phía máy chủ

Clustering

Hydration phía client

Thiết lập Vite

Cập nhật NPM script

Chạy SSR server

Tắt SSR

Triển khai

Laravel Cloud

Laravel Forge

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