React 入門 — 搭配 Inertia × Laravel 使用的基礎知識

什麼是 React

React 是 Meta（原 Facebook）開發並維護的使用者介面建構用 JavaScript 函式庫。特色是宣告式 UI 描述與元件式架構，從小型 widget 到完整 SPA 都能廣泛應用。 React 的核心是透過虛擬 DOM 有效率地重新繪製。當狀態（state）改變時，React 只把差異反映到 DOM，因此不必手動操作 DOM。

本頁介紹的是 React 19 與 Inertia v3 的組合。Laravel 13 啟動套件預設使用此組合。

JSX 與 TSX

React 元件以 JSX（JavaScript XML）語法撰寫，可在 JavaScript 內直接使用類似 HTML 的寫法。

// JSX 範例
function Greeting({ name }) {
    return <h1>你好，{name}</h1>
}

啟動套件標準採用 TypeScript（.tsx）。型別定義能加強 IDE 補完，並可及早發現 bug。

// TSX（TypeScript）範例
type Props = {
    name: string
}

function Greeting({ name }: Props) {
    return <h1>你好，{name}</h1>
}

Laravel React 啟動套件標準為 TypeScript + TSX。本頁範例全用 TSX 撰寫。

在 Laravel 中的定位

歷史

React 與 Laravel 的關係比 Vue 略淺，但目前已達到同等甚至更高的地位。 Laravel 6（2019 年） 將認證 scaffold 拆到 laravel/ui 套件，同時提供 Vue 與 React 版 scaffold。當時 Vue 為主流，React 版存在感較弱。 Laravel Breeze（2021 年） 加入 Inertia + React 堆疊後才正式獲得採用，Laravel 12（2025 年） 啟動套件全面翻新，React 與 Vue 已完全並列（甚至更早顯示）。

目前主流風格：Inertia × React

目前 Laravel 中 React 使用方式的核心是 Inertia × React。Inertia 實現「Modern Monolith」架構，不用設計 API 即可從 Laravel Controller 直接把資料傳給 React 元件。

建置

透過啟動套件（推薦）

新專案最省事的是使用啟動套件。

laravel new my-app

於互動式 prompt 選擇 React，以下項目會全部自動設定：

inertiajs/inertia-laravel（伺服器端 adapter）
@inertiajs/react（用戶端 adapter）
react + react-dom（React 19 本體）
@vitejs/plugin-react（Vite plugin）
TypeScript + @types/react
Tailwind CSS + shadcn/ui 元件庫
HandleInertiaRequests middleware
登入、註冊等認證畫面（以 Inertia + React + TypeScript 實作）

手動安裝

要加到既有專案，分別安裝伺服器端與用戶端。

# 伺服器端（PHP）
composer require inertiajs/inertia-laravel

# 用戶端（JavaScript）
npm install @inertiajs/react react react-dom
npm install --save-dev @vitejs/plugin-react @types/react @types/react-dom typescript

接著在 vite.config.ts 加入 React plugin。

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

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

於 resources/js/app.tsx 啟動 Inertia 應用。

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'

createInertiaApp({
    resolve: (name) =>
        resolvePageComponent(
            `./pages/${name}.tsx`,
            import.meta.glob('./pages/**/*.tsx'),
        ),
    setup({ el, App, props }) {
        createRoot(el).render(<App {...props} />)
    },
})

手動安裝細節（根樣板設定、middleware 註冊等）請參考 Inertia 官方文件。

目錄結構

啟動套件會把 React 頁面元件放到 resources/js/pages/。

resources/js/
├── app.tsx            # Inertia 應用起點
├── bootstrap.ts
├── components/        # 可重用 UI 元件
│   ├── ui/            # shadcn/ui 元件
│   └── ...
├── hooks/             # 自訂 React hook
├── layouts/           # Layout 元件
│   ├── app-layout.tsx
│   └── auth-layout.tsx
├── lib/               # 工具函式、設定
├── pages/             # Inertia 頁面元件（對應 Controller 名稱）
│   ├── auth/
│   │   ├── login.tsx
│   │   └── register.tsx
│   ├── dashboard.tsx
│   └── posts/
│       ├── index.tsx
│       ├── create.tsx
│       └── show.tsx
└── types/             # TypeScript 型別定義

寫 Inertia::render('posts/index', [...]) 時，resources/js/pages/posts/index.tsx 就是對應的元件。

JSX 語法基礎

React 使用 JSX，在 JavaScript 中寫類 HTML 語法。為了讀懂啟動套件的程式碼，以下是必知的模式。

`{}` — 變數展開

JSX 中用 {} 嵌入 JavaScript 值或運算式。

const name = '世界'
const count = 3

return (
    <div>
        <p>你好，{name}！</p>
        <p>兩倍是 {count * 2}</p>
    </div>
)

條件判斷 — `&&` 與三元運算子

React 沒有相當於 v-if 的指令。簡單條件用 &&，if/else 用三元運算子 ? :。

{/* 條件 true 才顯示 */}
{isLoggedIn && <p>歡迎！</p>}

{/* if / else */}
{isLoggedIn ? <p>歡迎！</p> : <a href="/login">登入</a>}

{/* if / else if / else */}
{isLoggedIn
    ? <p>歡迎！</p>
    : role === 'admin'
        ? <p>以管理員登入</p>
        : <a href="/login">登入</a>
}

列表渲染 — `.map()`

列表渲染用 Array.map()。為了差異更新有效率，key prop 必須指定。

<ul>
    {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
    ))}
</ul>

相當於 Vue 的 v-for :key 或 Svelte 的 {#each}。

`className` — CSS class 名稱

JSX 會被編譯為 JavaScript，class 為保留字，因此 CSS class 使用 className。

{/* HTML：<div class="container"> */}
<div className="container">...</div>

事件 handler — 駝峰式

JSX 的事件屬性用駝峰式，並傳入函式參考。

<button onClick={handleClick}>點擊</button>

{/* 取消表單預設送出 */}
<form onSubmit={(e) => { e.preventDefault(); handleSubmit() }}>
    ...
</form>

頁面元件基礎

Inertia 頁面元件就是一般的 React 元件。由 Laravel Controller 傳來的資料以 props 接收。

Controller

// app/Http/Controllers/PostController.php
use Inertia\Inertia;
use App\Models\Post;

class PostController extends Controller
{
    public function index()
    {
        return Inertia::render('posts/index', [
            'posts' => Post::latest()->paginate(10),
        ]);
    }
}

React 頁面元件

// resources/js/pages/posts/index.tsx
import { Link } from '@inertiajs/react'

type Post = {
    id: number
    title: string
    created_at: string
}

type Props = {
    posts: {
        data: Post[]
        // paginate(10) 會傳回含分頁資訊的物件
        // current_page、last_page、per_page、total 等也可用
    }
}

export default function PostsIndex({ posts }: Props) {
    return (
        <div>
            <h1>貼文列表</h1>
            {posts.data.map((post) => (
                <article key={post.id}>
                    <h2>
                        <Link href={`/posts/${post.id}`}>{post.title}</Link>
                    </h2>
                    <p>{post.created_at}</p>
                </article>
            ))}
        </div>
    )
}

元件只要以參數接收 props 即可使用 Controller 傳來的資料。不需要定義 REST API。

`Link` 元件

使用 @inertiajs/react 提供的 <Link> 元件時，頁面切換會以 XHR 進行，可避免瀏覽器全頁重新載入。

import { Link } from '@inertiajs/react'

export default function PostsIndex() {
    return (
        <div>
            {/* 基本連結 */}
            <Link href="/posts">貼文列表</Link>

            {/* 以 POST 方法送出的連結（例如刪除） */}
            <Link href="/posts/1" method="delete" as="button">
                刪除
            </Link>

            {/* preload（hover 時預先取得） */}
            <Link href="/posts/1" preload>
                查看貼文
            </Link>
        </div>
    )
}

寫法就像一般 <a> 標籤，但幕後 Inertia 只替換頁面元件，因而有 SPA 般的操作感。

`Form` 元件

@inertiajs/react 提供的 <Form> 元件是啟動套件認證畫面採用的推薦表單樣式。以 props 指定 action 與 method，並以 children 函式（render prop）接收 errors 與 processing。

基本用法

import { Form } from '@inertiajs/react'

export default function PostCreate() {
    return (
        <Form action="/posts" method="post" className="flex flex-col gap-4">
            {({ errors, processing }) => (
                <>
                    <div>
                        <label htmlFor="title">標題</label>
                        <input id="title" name="title" type="text" required />
                        {errors.title && <p className="error">{errors.title}</p>}
                    </div>

                    <div>
                        <label htmlFor="content">內容</label>
                        <textarea id="content" name="content" />
                        {errors.content && <p className="error">{errors.content}</p>}
                    </div>

                    <button type="submit" disabled={processing}>
                        {processing ? '送出中...' : '發佈'}
                    </button>
                </>
            )}
        </Form>
    )
}

<Form> 的 children 是 ({ errors, processing }) => JSX 的函式（render prop 模式）。Form 元件會自動算出並傳入這些值。表單欄位不使用 onChange handler，而是使用 HTML 原生的 name 屬性，交由瀏覽器標準的表單資料收集機制。

啟動套件的模式

啟動套件用 Wayfinder 將路由當作物件管理。store.form() 會回傳含有路由物件 action 與 method 的物件，用 spread 傳給 <Form>。

import { Form } from '@inertiajs/react'
import { store } from '@/routes/login'

export default function Login() {
    return (
        <Form
            {...store.form()}
            resetOnSuccess={['password']}
            className="flex flex-col gap-6"
        >
            {({ errors, processing }) => (
                <>
                    {/* 表單內容 */}
                </>
            )}
        </Form>
    )
}

指定於 resetOnSuccess 的欄位，會在送出成功時自動重置。可指定密碼等送出後想清空的欄位。

不使用 Wayfinder 時，直接傳 action="/login" 這樣的 URL 也能同樣運作。

`useForm` hook

表單處理使用 @inertiajs/react 的 useForm hook，能簡潔實作表單狀態管理、送出、驗證錯誤顯示。

Controller 端

// app/Http/Controllers/PostController.php
class PostController extends Controller
{
    public function store(Request $request)
    {
        $validated = $request->validate([
            'title'   => ['required', 'string', 'max:255'],
            'content' => ['required', 'string'],
        ]);

        Post::create($validated + ['user_id' => auth()->id()]);

        return redirect()->route('posts.index')
            ->with('success', '貼文已建立。');
    }
}

React 表單元件

// resources/js/pages/posts/create.tsx
import { useForm } from '@inertiajs/react'
import { FormEventHandler } from 'react'

export default function PostCreate() {
    const { data, setData, post, processing, errors } = useForm({
        title: '',
        content: '',
    })

    const submit: FormEventHandler = (e) => {
        e.preventDefault()
        post('/posts')
    }

    return (
        <form onSubmit={submit}>
            <div>
                <label>標題</label>
                <input
                    type="text"
                    value={data.title}
                    onChange={(e) => setData('title', e.target.value)}
                />
                {errors.title && <p className="error">{errors.title}</p>}
            </div>

            <div>
                <label>內容</label>
                <textarea
                    value={data.content}
                    onChange={(e) => setData('content', e.target.value)}
                />
                {errors.content && <p className="error">{errors.content}</p>}
            </div>

            <button type="submit" disabled={processing}>
                {processing ? '送出中...' : '發佈'}
            </button>
        </form>
    )
}

useForm 回傳物件的主要屬性整理如下。

屬性 / 方法	說明
`data`	表單資料物件
`setData(field, value)`	更新欄位值
`errors`	驗證錯誤（以欄位名稱存取）
`processing`	送出中為 `true`（可用於停用按鈕）
`isDirty`	已被修改過為 `true`
`post(url)`	以 POST 送出
`put(url)`	以 PUT 送出（更新）
`delete(url)`	以 DELETE 送出
`reset()`	重置為初始值

發生驗證錯誤時，useForm 會保留輸入內容並顯示錯誤。

共用資料（Shared Data）

所有頁面共通所需的資料（登入中使用者資訊、flash 訊息等），在 HandleInertiaRequests middleware 的 share() 方法中定義。

// app/Http/Middleware/HandleInertiaRequests.php
use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            'auth' => [
                'user' => $request->user()
                    ? $request->user()->only('id', 'name', 'email')
                    : null,
            ],
            'flash' => [
                'success' => $request->session()->get('success'),
                'error'   => $request->session()->get('error'),
            ],
        ]);
    }
}

React 元件從 usePage() hook 存取共用資料。

import { usePage } from '@inertiajs/react'

type SharedProps = {
    auth: {
        user: { id: number; name: string; email: string } | null
    }
    flash: {
        success: string | null
        error: string | null
    }
}

export default function AppHeader() {
    const { auth, flash } = usePage<SharedProps>().props

    return (
        <>
            <header>
                {auth.user ? (
                    <span>{auth.user.name}</span>
                ) : (
                    <span>訪客</span>
                )}
            </header>

            {flash.success && (
                <div className="alert-success">{flash.success}</div>
            )}
        </>
    )
}

共用資料會包含在每次請求中，建議只放最必要的內容。以 fn() 進行 lazy evaluation，就只有在真正被存取時才會被求值。

React hook 基礎

在 Inertia × React 開發中，該掌握的 React 基本 hook 如下。

`useState` — 本地狀態管理

import { useState } from 'react'

export default function Counter() {
    const [count, setCount] = useState(0)
    const [isOpen, setIsOpen] = useState(false)

    return (
        <div>
            <p>{count}</p>
            <button onClick={() => setCount(count + 1)}>+1</button>
            <button onClick={() => setIsOpen(!isOpen)}>切換</button>
        </div>
    )
}

`useEffect` — 副作用處理

import { useState, useEffect } from 'react'

export default function Timer() {
    const [seconds, setSeconds] = useState(0)

    useEffect(() => {
        const timer = setInterval(() => {
            setSeconds((s) => s + 1)
        }, 1000)

        // 清理函式
        return () => clearInterval(timer)
    }, []) // 空陣列 = 只在掛載時執行一次

    return <p>經過時間：{seconds} 秒</p>
}

`useMemo` 與 `useCallback` — 效能最佳化

import { useMemo, useCallback } from 'react'
import { router } from '@inertiajs/react'

type Post = { id: number; title: string; published: boolean }
type Props = { posts: Post[] }

export default function PostsList({ posts }: Props) {
    // 值 memoize（posts 沒變就不重算）
    const publishedPosts = useMemo(
        () => posts.filter((post) => post.published),
        [posts],
    )

    // 函式 memoize（相依值沒變就不重建）
    const handleClick = useCallback((id: number) => {
        router.visit(`/posts/${id}`)
    }, [])

    return (
        <ul>
            {publishedPosts.map((post) => (
                <li key={post.id} onClick={() => handleClick(post.id)}>
                    {post.title}
                </li>
            ))}
        </ul>
    )
}

TypeScript 支援

啟動套件的 React 版預設使用 TypeScript。與 Inertia 的型別定義結合，可確保 props 的型別安全。

全域型別定義

啟動套件在 resources/js/types/index.d.ts 定義共用資料型別。

// resources/js/types/index.d.ts
export interface User {
    id: number
    name: string
    email: string
    email_verified_at?: string
}

export type PageProps<T extends Record<string, unknown> = Record<string, unknown>> = T & {
    auth: {
        user: User
    }
}

於頁面元件使用型別

import { PageProps } from '@/types'

type Post = {
    id: number
    title: string
    content: string
}

export default function PostsIndex({ auth, posts }: PageProps<{ posts: Post[] }>) {
    return (
        <div>
            <p>登入中：{auth.user.name}</p>
            {posts.map((post) => (
                <article key={post.id}>
                    <h2>{post.title}</h2>
                </article>
            ))}
        </div>
    )
}

總結

React 與 Laravel 搭配時，透過 Inertia 的「Modern Monolith」架構最能發揮實力。與 TypeScript 的相容性也極佳，適合大型應用開發。

元素	角色
Laravel Controller	路由、資料取得、驗證
`Inertia::render()`	從 Controller 把資料傳給 React 元件
React 頁面元件	接收 props 並渲染 UI
`useForm`	表單狀態管理、送出、錯誤顯示
`Link` 元件	無全頁載入的頁面切換
`usePage().props`	存取共用資料
TypeScript	props 型別安全、加強 IDE 補完

Inertia × React 可獲得 Laravel 後端的簡潔與 React 強大生態系兼具的開發體驗。啟動套件建立專案後含認證畫面在內都能馬上開始開發。

Inertia.js 官方文件

Inertia v3 完整功能請參考官方文件。

​什麼是 React

​JSX 與 TSX

​在 Laravel 中的定位

​歷史

​目前主流風格：Inertia × React

​建置

​透過啟動套件（推薦）

​手動安裝

​目錄結構

​JSX 語法基礎

​{} — 變數展開

​條件判斷 — && 與三元運算子

​列表渲染 — .map()

​className — CSS class 名稱

​事件 handler — 駝峰式

​頁面元件基礎

​Controller

​React 頁面元件

​Link 元件

​Form 元件

​基本用法

​啟動套件的模式

​useForm hook

​Controller 端

​React 表單元件

​共用資料（Shared Data）

​React hook 基礎

​useState — 本地狀態管理

​useEffect — 副作用處理

​useMemo 與 useCallback — 效能最佳化

​TypeScript 支援

​全域型別定義

​於頁面元件使用型別

​總結

Inertia.js 官方文件

什麼是 React

JSX 與 TSX

在 Laravel 中的定位

歷史

目前主流風格：Inertia × React

建置

透過啟動套件（推薦）

手動安裝

目錄結構

JSX 語法基礎

`{}` — 變數展開

條件判斷 — `&&` 與三元運算子

列表渲染 — `.map()`

`className` — CSS class 名稱

事件 handler — 駝峰式

頁面元件基礎

Controller

React 頁面元件

`Link` 元件

`Form` 元件

基本用法

啟動套件的模式

`useForm` hook

Controller 端

React 表單元件

共用資料（Shared Data）

React hook 基礎

`useState` — 本地狀態管理

`useEffect` — 副作用處理

`useMemo` 與 `useCallback` — 效能最佳化

TypeScript 支援

全域型別定義

於頁面元件使用型別

總結