> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 起始套件（Starter Kit）

> 使用 Laravel 的起始套件快速設定認證與 UI 的方式

## 什麼是起始套件

起始套件是 Laravel 應用作為出發點所準備的官方 scaffolding。
可一次設定登入、註冊、密碼重設、電子郵件驗證等認證功能與相對應的 UI。

在使用 `laravel new` 建立應用時只需選擇起始套件，認證相關的路由、controller、view、前端程式碼就會全部自動產生。
產生的程式碼都在自己的應用內，可自由自訂。

<Warning>
  在 Laravel 13 中，過去的 **Breeze** 與 **Jetstream** 已停用。
  新專案請使用下面介紹的起始套件。
  使用 Breeze 或 Jetstream 的既有專案仍能運作，但不建議用於新開發。
</Warning>

## 可用的起始套件

Laravel 13 提供以下 4 種起始套件：

<CardGroup cols={2}>
  <Card title="React" icon="react">
    使用 React 19、TypeScript、Tailwind 4、[shadcn/ui](https://ui.shadcn.com) 的現代 SPA。
    透過 [Inertia.js](https://inertiajs.com) 可以在保留伺服器端路由的同時使用 React。
  </Card>

  <Card title="Vue" icon="vuejs">
    採用 Vue 3 Composition API、TypeScript、Tailwind、[shadcn-vue](https://www.shadcn-vue.com/)。
    與 React 一樣以 Inertia.js 與伺服器端整合。
  </Card>

  <Card title="Livewire" icon="bolt">
    只用 PHP 就能建構動態 UI 的 [Livewire](https://livewire.laravel.com)。
    適合以 Blade 樣板為中心的團隊、或不想使用 JavaScript 框架的情況。採用 [Flux UI](https://fluxui.dev)。
  </Card>

  <Card title="Svelte" icon="s">
    使用 Svelte 5、TypeScript、Tailwind、[shadcn-svelte](https://www.shadcn-svelte.com/) 的 SPA。
    可與 Inertia.js 搭配建構現代前端。
  </Card>
</CardGroup>

### 該選哪一個

| 起始套件     | 適合的團隊                        |
| -------- | ---------------------------- |
| React    | 熟悉 React 生態系或 TypeScript 的團隊 |
| Vue      | 有 Vue 或 Nuxt 經驗的團隊           |
| Livewire | 想以 PHP 與 Blade 為中心開發的團隊      |
| Svelte   | 有 Svelte 或 SvelteKit 經驗的團隊   |

<Tip>
  無論選哪一個，認證功能都完全相同。請選團隊最熟悉的前端技術。
</Tip>

<Info>
  想從整體角度理解 Blade、Livewire、Inertia、獨立 SPA 差異時，可先閱讀 [前端](/zh-TW/frontend) 會較易選擇。
</Info>

## 安裝方式

起始套件在建立專案時選擇。執行 `laravel new` 指令時會以互動方式選擇起始套件。

<Steps>
  <Step title="安裝 Laravel installer">
    若尚未安裝，用 Composer 取得 Laravel installer。

    ```bash theme={null}
    composer global require laravel/installer
    ```
  </Step>

  <Step title="建立新應用">
    執行 `laravel new` 指令，會顯示包含起始套件選擇的互動式提示。

    ```bash theme={null}
    laravel new my-app
    ```

    在提示中選擇 **React**、**Vue**、**Livewire** 或 **Svelte**。
    也可選擇認證 provider 是標準 Laravel 認證或 WorkOS AuthKit。
  </Step>

  <Step title="安裝前端相依">
    ```bash theme={null}
    cd my-app
    npm install && npm run build
    ```
  </Step>

  <Step title="準備資料庫">
    確認 `.env` 檔案的資料庫設定後執行 migration。

    ```bash theme={null}
    php artisan migrate
    ```
  </Step>

  <Step title="啟動開發伺服器">
    ```bash theme={null}
    composer run dev
    ```

    以瀏覽器訪問 `http://localhost:8000`，導覽列會顯示「Register」「Log in」連結。
  </Step>
</Steps>

安裝起始套件後，可立即使用以下認證功能：

| 功能     | URL                 |
| ------ | ------------------- |
| 使用者註冊  | `/register`         |
| 登入     | `/login`            |
| 密碼重設   | `/forgot-password`  |
| 電子郵件驗證 | `/email/verify`     |
| 個人資料編輯 | `/settings/profile` |

## 起始套件的自訂

產生的程式碼都在自己的應用內，因此可自由變更。
前端程式碼大多位於 `resources/js`（Livewire 為 Blade，位於 `resources/views`）目錄。

### 切換版面配置

各起始套件提供「sidebar」與「header」兩種版面配置。
預設為 sidebar 版面配置。

<Tabs>
  <Tab title="React">
    編輯 `resources/js/layouts/app-layout.tsx`。

    ```tsx theme={null}
    // sidebar 版面配置（預設）
    import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout';

    // 改用 header 版面配置
    import AppLayoutTemplate from '@/layouts/app/app-header-layout';
    ```
  </Tab>

  <Tab title="Vue">
    編輯 `resources/js/layouts/AppLayout.vue`。

    ```js theme={null}
    // sidebar 版面配置（預設）
    import AppLayout from '@/layouts/app/AppSidebarLayout.vue';

    // 改用 header 版面配置
    import AppLayout from '@/layouts/app/AppHeaderLayout.vue';
    ```
  </Tab>

  <Tab title="Livewire">
    編輯 `resources/views/layouts/app.blade.php`。

    ```blade theme={null}
    {{-- 改用 header 版面配置 --}}
    <x-layouts::app.header>
        <flux:main container>
            {{ $slot }}
        </flux:main>
    </x-layouts::app.header>
    ```
  </Tab>

  <Tab title="Svelte">
    編輯 `resources/js/layouts/AppLayout.svelte`。

    ```js theme={null}
    // sidebar 版面配置（預設）
    import AppLayout from '@/layouts/app/AppSidebarLayout.svelte';

    // 改用 header 版面配置
    import AppLayout from '@/layouts/app/AppHeaderLayout.svelte';
    ```
  </Tab>
</Tabs>

### 變更認證頁面的版面配置

登入或註冊頁也可以從「simple」「card」「split」三種版面配置中選擇。

<Tabs>
  <Tab title="React">
    編輯 `resources/js/layouts/auth-layout.tsx`。

    ```tsx theme={null}
    // simple 版面配置（預設）
    import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout';

    // 改為 split 版面配置
    import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';
    ```
  </Tab>

  <Tab title="Vue">
    編輯 `resources/js/layouts/AuthLayout.vue`。

    ```js theme={null}
    import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue';

    // 改為 split 版面配置
    import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';
    ```
  </Tab>

  <Tab title="Livewire">
    編輯 `resources/views/layouts/auth.blade.php`。

    ```blade theme={null}
    <x-layouts::auth.split>
        {{ $slot }}
    </x-layouts::auth.split>
    ```
  </Tab>

  <Tab title="Svelte">
    編輯 `resources/js/layouts/AuthLayout.svelte`。

    ```js theme={null}
    import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte';

    // 改為 split 版面配置
    import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte';
    ```
  </Tab>
</Tabs>

### 自訂使用者註冊邏輯

起始套件將使用者註冊與密碼重設的處理交由 `app/Actions/Fortify` 目錄下的 action 類別。
例如註冊時要加入電話欄位，可編輯 `CreateNewUser.php`。

```php theme={null}
public function create(array $input): User
{
    Validator::make($input, [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email', 'max:255', 'unique:users'],
        'phone' => ['required', 'string', 'max:20'],
        'password' => $this->passwordRules(),
    ])->validate();

    return User::create([
        'name' => $input['name'],
        'email' => $input['email'],
        'phone' => $input['phone'],
        'password' => Hash::make($input['password']),
    ]);
}
```

## WorkOS AuthKit 認證

執行 `laravel new` 時，也可選擇 **WorkOS AuthKit** 作為認證 provider。
選擇 WorkOS AuthKit 會追加下列功能：

* 社群認證（Google、Microsoft、GitHub、Apple）
* Passkey 認證
* 透過 email 的「Magic Auth」
* SSO（單一登入）

<Info>
  使用 WorkOS AuthKit 需要 WorkOS 帳號。月活躍使用者 100 萬人以內免費。
</Info>

若選擇 WorkOS，於 `.env` 檔設定下列環境變數：

```ini theme={null}
WORKOS_CLIENT_ID=your-client-id
WORKOS_API_KEY=your-api-key
WORKOS_REDIRECT_URL="${APP_URL}/authenticate"
```

## 注意事項

<Warning>
  起始套件是在**建立專案時**選擇的。
  無法之後才追加到既有專案。
  若需要認證 UI，請在新專案中選擇起始套件，或手動實作認證功能。
</Warning>

## 後續步驟

<Card title="認證入門" icon="lock" href="/zh-TW/authentication">
  進一步了解 `Auth` facade 的用法、路由保護等 Laravel 認證功能。
</Card>


## Related topics

- [Feedable](/zh-TW/packages/feedable/index.md)
- [密碼重設](/zh-TW/passwords.md)
- [電子郵件驗證（Email Verification）](/zh-TW/verification.md)
- [Laravel Package Skeleton — 官方套件用起始模板](/zh-TW/blog/package-skeleton-introduction.md)
- [Laravel Console Starter](/zh-TW/packages/laravel-console-starter/index.md)