> ## 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의 4종류가 있고, 인증과 초기 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](/ko/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에 명기한다">
    사용자 대상으로 다음의 도입 커맨드를 기재합니다.

    ```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나 컴포넌트 라이브러리, 인증 방식을 자유롭게 정해도 문제없습니다.

| 선택지                                | 주요 구성                             | 적합한 케이스                            |
| ---------------------------------- | --------------------------------- | ---------------------------------- |
| 공식 React / Vue / Svelte / Livewire | Inertia 3나 Livewire 4를 사용하는 공식 구성 | 공식에 가까운 개발 경험을 제공하고 싶은 경우          |
| 독자 프론트엔드                           | 임의의 CSS나 컴포넌트 라이브러리               | 기존 디자인 시스템이나 다른 CSS 기반을 사용하고 싶은 경우 |
| 심플 Blade 킷                         | Blade 중심, 최소한의 프론트 의존             | 경량 구성으로 빠르게 도입하고 싶은 경우             |
| 독자 인증 킷                            | 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
* 컴포넌트 라이브러리 (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 릴리스 직후 바로 추종할 수 있는 운용을 만들어 주세요.
* **관련 가이드를 함께 읽는다**: [패키지 개발의 기초](/ko/advanced/package-development)와 [패키지의 버전 호환성 관리](/ko/advanced/package-versioning)를 함께 읽으면 설계가 안정됩니다.


## Related topics

- [Laravel Fortify와 스타터 킷](/ko/advanced/fortify.md)
- [Laravel Maestro — 스타터 킷 개발의 오케스트레이터](/ko/blog/maestro-introduction.md)
- [스타터 킷](/ko/starter-kits.md)
- [Laravel Console Starter](/ko/packages/laravel-console-starter/index.md)
- [Laravel Chisel — 스타터 킷의 포스트 인스톨 스크립트 라이브러리](/ko/blog/chisel-introduction.md)