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

# Laravel 啟動套件的建立方式

> 說明如何建立 Laravel 啟動套件、發布至 Packagist，並持續因應 Laravel 與前端版本升級的實務流程。

## 前言

啟動套件是於 `laravel new` 建立應用程式時，透過 `create-project` 展開的範本專案。Laravel 13 的官方啟動套件有 React / Vue / Svelte / Livewire 四種，包含驗證與初始 UI。

當您要建立自訂啟動套件時，該做的事情相同。以 Laravel 應用程式為基礎進行整備後，作為 Composer 套件公開。

* 官方文件：[Starter Kits](https://laravel.com/docs/starter-kits)
* 官方實作範例：[laravel/react-starter-kit](https://github.com/laravel/react-starter-kit)
* 參考頁面：[Laravel Console Starter](/zh-TW/packages/laravel-console-starter/index)

## 啟動套件的建立

### 初始化 Laravel 專案

首先建立作為範本的 Laravel 專案，並整理不需要的範例程式碼。接著在 `composer.json` 的 `name` 中設定唯一的套件名稱。

```json theme={null}
{
    "name": "example/starter-kit",
    "type": "project",
    "require": {
        "php": "^8.3",
        "laravel/framework": "^13.0"
    }
}
```

此 `name` 就是稍後於 `laravel new my-app --using=example/starter-kit` 中使用的識別碼。

### 設定 composer.json 的 scripts

於 `laravel new` 執行後，啟動套件端的 Composer scripts 會用於初始化流程。至少要備齊 `post-root-package-install` 與 `post-create-project-cmd`。

```json theme={null}
"scripts": {
    "post-root-package-install": [
        "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
    ],
    "post-create-project-cmd": [
        "@php artisan key:generate --ansi",
        "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
        "@php artisan migrate --graceful --ansi"
    ]
}
```

此範例是以 [laravel/react-starter-kit 的 composer.json](https://github.com/laravel/react-starter-kit/blob/main/composer.json) 為基礎的組成。若使用資料庫可直接沿用。

### 以 .gitattributes 控制發布對象

將希望存在於啟動套件儲存庫但不希望包含於使用者生成專案中的檔案，以 `export-ignore` 排除。

```gitattributes theme={null}
LICENSE export-ignore
composer.lock export-ignore
README.md export-ignore
```

詳情請參考 [.gitattributes 的官方範例](https://github.com/laravel/react-starter-kit/blob/main/.gitattributes)。

## 於 Packagist 註冊

若要讓使用者可透過 `--using` 使用，需於 Packagist 註冊。

<Steps>
  <Step title="於 GitHub 準備公開儲存庫">
    使 `composer.json` 的 `name` 與儲存庫 URL 一致並公開。
  </Step>

  <Step title="於 Packagist 註冊">
    於 [Packagist](https://packagist.org/) 註冊儲存庫。公開後 `example/starter-kit` 便可被解析。
  </Step>

  <Step title="於 README 明確標示使用指令">
    於 README 為使用者記載下列導入指令。

    ```bash theme={null}
    laravel new my-app --using=example/starter-kit
    ```
  </Step>
</Steps>

## laravel new 指令的流程

`laravel/installer` 的 `NewCommand` 於指定啟動套件時會切換 `create-project` 目標並依序執行初始化指令。

```mermaid theme={null}
flowchart TD
    A["laravel new my-app --using=example/starter-kit"] --> B["以 getStarterKit() 決定套件名稱"]
    B --> C["composer create-project example/starter-kit my-app"]
    C --> D["composer run post-root-package-install -d my-app"]
    D --> E["artisan key:generate 等初始化處理"]
    E --> F["視需要執行 migrate / npm install"]
```

於 [NewCommand.php](https://github.com/laravel/installer/blob/master/src/NewCommand.php) 想確認的部分：

* [--using 選項定義](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L119)
* [`create-project` 與 `post-root-package-install` 的執行](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L521-L569)
* [`getStarterKit()` 的實作](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L1237-L1255)

## 前端框架的選擇

Laravel 13 的官方啟動套件提供 React / Vue / Svelte / Livewire，但自訂啟動套件不必配合此組合。可依目的自由決定 CSS 或 component library、驗證方式。

| 選項                                 | 主要組成                            | 適用情境                 |
| ---------------------------------- | ------------------------------- | -------------------- |
| 官方 React / Vue / Svelte / Livewire | 使用 Inertia 3 或 Livewire 4 的官方組成 | 希望提供貼近官方的開發體驗        |
| 自訂前端                               | 任意 CSS 或 component library      | 希望使用既有設計系統或不同 CSS 基礎 |
| 簡易 Blade Kit                       | 以 Blade 為主、最小前端相依               | 希望以輕量組成快速導入          |
| 自訂驗證 Kit                           | 不限於 Fortify（例如以 Socialite 為主）   | 希望限定特定驗證方式           |

<Info>
  社群啟動套件通常會採用與官方不同的 CSS 基礎。驗證也不必以 Fortify 為前提，請依需求設計。
</Info>

## 版本升級維護

啟動套件並非「建立後就結束」。要配合 Laravel 或 PHP 的更新持續跟進。

### Laravel、PHP 版本升級對應

首先更新 `composer.json` 的要求，並於 CI 確認相容性。

```json theme={null}
"require": {
    "php": "^8.3",
    "laravel/framework": "^13.0"
}
```

於 Laravel 主版本升級時，請同時檢視 `laravel/framework` 與周邊相依。

### 定期更新相依套件

前端相依變化較快，建議每月排入更新任務較為安全。

* Tailwind
* component library（shadcn/ui、shadcn-vue、shadcn-svelte、Flux UI）
* Inertia / Livewire 相關套件

### 相容性測試

CI 中至少應加入下列確認。

* `composer install` 是否成功
* `php artisan test` 是否通過
* `npm install && npm run build` 是否通過

## 最佳實踐

* **`name` 於早期確定**：於 Packagist 公開後變更成本高。
* **scripts 以官方範例為基準**：破壞初始化流程會使導入失敗增加。
* **首先整備 `.gitattributes`**：可減少範本發布時的雜訊。
* **升級常態化**：建立可於 Laravel 發布後立即跟進的運作。
* **合併閱讀相關指南**：合併閱讀[套件開發基礎](/zh-TW/advanced/package-development)與[套件的版本相容性管理](/zh-TW/advanced/package-versioning)可使設計更穩定。


## Related topics

- [Laravel Chisel — 啟動套件的安裝後腳本函式庫](/zh-TW/blog/chisel-introduction.md)
- [用 Inertia.js 建構 SPA](/zh-TW/blog/inertia-introduction.md)
- [核心套件與自訂驅動 - Feedable](/zh-TW/packages/feedable/core.md)
- [Laravel Maestro — 啟動套件開發的協調器](/zh-TW/blog/maestro-introduction.md)
- [以 Testbench Workbench 推進套件開發](/zh-TW/advanced/package-workbench.md)