> ## 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 Package Skeleton — 공식 패키지용 스타터 템플릿

> laravel/package-skeleton 초기 조사. Laravel 패키지 개발의 베스트 프랙티스를 모은 공식 스타터 템플릿. Pest · Larastan · Pint · Workbench · GitHub Actions CI를 포함한 올인원 구성.

<Info>
  이 글은 소스 코드 조사에 기반한 정보입니다. 2026년 7월 시점에서 개발 중인 리포지토리입니다.
</Info>

## Laravel Package Skeleton이란

[Laravel Package Skeleton](https://github.com/laravel/package-skeleton)은 Laravel 패키지를 만들 때의 스타터 템플릿입니다.

```bash theme={null}
git clone https://github.com/laravel/package-skeleton.git my-package
cd my-package
composer install
```

`composer install`을 실행하면 대화형 설정 스크립트(`configure.php`)가 자동 기동하여, 패키지명 · 벤더명 · 네임스페이스 · 사용할 기능을 일문일답으로 설정합니다. 설정 후에는 즉시 개발을 시작할 수 있는 상태가 됩니다.

```mermaid theme={null}
graph TD
    A["GitHub에서<br>Use this template"] --> B["composer install"]
    B --> C["configure.php가 자동 실행"]
    C --> D{"대화형 설정"}
    D --> E["패키지명 · 벤더 · 네임스페이스"]
    D --> F["사용할 기능 선택"]
    E --> G["설정 완료"]
    F --> G
    G --> H["composer test로 동작 확인"]
```

## 왜 이 스켈레톤이 필요한가

Laravel 패키지를 "자기 방식"으로 만들기 시작하면, 테스트 환경 셋업 · 정적 해석 · 코드 포맷 · GitHub Actions 설정 등, 본래의 패키지 로직과는 무관한 작업에 많은 시간을 소비합니다.

Laravel Package Skeleton은 Laravel 팀이 실제 패키지 개발에서 사용하는 베스트 프랙티스를 하나의 템플릿으로 정리한 것입니다. 템플릿을 사용하면 "환경 구축"을 건너뛰고 패키지 로직 구현부터 바로 시작할 수 있습니다.

## 포함되는 도구

| 도구                                                       | 역할             |
| -------------------------------------------------------- | -------------- |
| [Pest](https://pestphp.com/)                             | 테스트 프레임워크      |
| [Larastan](https://github.com/larastan/larastan)         | Laravel용 정적 해석 |
| [Pint](https://laravel.com/docs/pint)                    | 코드 포맷터         |
| [Orchestra Testbench](https://packages.tools/testbench/) | 패키지 테스트 환경     |
| Workbench                                                | 엔드투엔드 개발용 앱    |

## 설정 가능한 패키지 기능

`composer install` 시의 프롬프트에서 필요한 기능만을 선택할 수 있습니다. 선택하지 않은 기능에 관한 스캐폴드는 삭제됩니다.

| 기능           | 설명                  |
| ------------ | ------------------- |
| Config file  | `config/`에 설정 파일 추가 |
| Routes       | 라우트 파일 추가           |
| Views        | Blade 뷰 추가          |
| Translations | 언어 파일 추가            |
| Migrations   | 마이그레이션 파일 추가        |
| Assets       | 공개용 애셋 추가           |
| Commands     | Artisan 명령 추가       |
| Facade       | 파사드 클래스 추가          |
| Boost Skill  | AI 에이전트용 스킬 추가      |

## 설정 가능한 도구

기능과 마찬가지로, 프로젝트에 따라 도구의 온/오프도 선택할 수 있습니다.

| 도구              | 설명                        |
| --------------- | ------------------------- |
| Dependabot      | 의존관계의 자동 갱신 PR            |
| Issue Template  | GitHub Issue 템플릿          |
| Changelog       | 릴리스 시의 자동 CHANGELOG.md 갱신 |
| Funding         | GitHub Sponsors 스폰서 링크    |
| Security Policy | 보안 취약성 보고 정책              |

## 셋업의 흐름

<Steps>
  <Step title="템플릿에서 리포지토리 생성">
    GitHub의 **Use this template** 버튼을 눌러 새 리포지토리를 만들거나, 직접 클론합니다.

    ```bash theme={null}
    git clone https://github.com/laravel/package-skeleton.git my-package
    cd my-package
    ```
  </Step>

  <Step title="의존관계 설치">
    `composer install`을 실행하면 `configure.php`가 자동 기동합니다.

    ```bash theme={null}
    composer install
    ```

    스크립트를 수동으로 실행하고 싶은 경우는 `--no-scripts` 옵션을 사용합니다.

    ```bash theme={null}
    composer install --no-scripts
    php configure.php
    ```
  </Step>

  <Step title="프롬프트에 응답">
    이하 항목을 일문일답으로 설정합니다.

    * Author Name / Email
    * Vendor 이름 (예: `kawax`)
    * Package 이름 (예: `my-package`)
    * Package 설명문
    * Class 이름 (예: `MyPackage`)
    * 사용할 기능의 멀티 선택
    * 사용할 도구의 멀티 선택
    * GitHub 리포지토리의 자동 생성 (gh CLI가 인증된 경우)
  </Step>

  <Step title="동작 확인">
    ```bash theme={null}
    composer test
    ```

    PHPStan → Pint → 타입 커버리지 → Pest 순으로 전 체크를 실행합니다.
  </Step>

  <Step title="Workbench에서 엔드투엔드 테스트">
    ```bash theme={null}
    composer serve
    ```

    `http://localhost:8000`에 패키지 확인용 간이 Laravel 앱이 기동합니다.
  </Step>
</Steps>

## 비대화 모드

CI나 스크립트에서 셋업하는 경우는 `--no-interaction` 플래그를 사용합니다.

```bash theme={null}
php configure.php --no-interaction --config --routes
```

기능 플래그를 지정하면 지정한 기능만이 포함됩니다. 플래그를 생략하면 모든 기능이 포함됩니다.

## GitHub Actions CI

스켈레톤에 포함되는 `tests.yml`은 여러 PHP 버전 · Laravel 버전 · OS의 조합으로 테스트를 실행하는 매트릭스 빌드입니다.

```yaml theme={null}
matrix:
  os: [ubuntu-latest, windows-latest]
  php: [8.3, 8.4, 8.5]
  laravel: [12.*, 13.*]
  stability: [prefer-lowest, prefer-stable]
```

각 잡에서 실행되는 내용:

1. **PHPStan** (`composer analyse`) — 정적 해석
2. **Pint** (`composer lint:check`) — 스타일 체크
3. **타입 커버리지** (`composer test:types`) — 타입 커버리지 100% 확인 (Ubuntu만)
4. **Pest** (`composer test:unit`) — 유닛 테스트 (Ubuntu만)

## Changelog 자동화

`update-changelog.yml`이 GitHub Release를 트리거로 `CHANGELOG.md`를 자동 갱신합니다. `release.yml`에서 PR 라벨별로 변경 내용을 분류하여 릴리스 노트를 생성합니다.

릴리스 노트의 라벨:

| 라벨               | 분류             |
| ---------------- | -------------- |
| `breaking`       | 파괴적 변경         |
| `enhancement`    | 기능 추가          |
| `bug`            | 버그 수정          |
| `documentation`  | 문서             |
| `dependencies`   | 의존관계           |
| `maintenance`    | 메인터넌스          |
| `skip-changelog` | 변경 이력에 포함하지 않음 |

## configure.php가 하는 일

`configure.php`는 설정 스크립트로 한 번만 실행하는 bootstrap입니다. 실행 후에는 삭제됩니다.

```mermaid theme={null}
graph LR
    A["configure.php 실행"] --> B["플레이스홀더 치환<br>:vendor_slug/:package_slug<br>:author_name 등"]
    B --> C["미사용 기능 파일 삭제"]
    C --> D["README_PACKAGE.md → README.md<br>AGENTS_PACKAGE.md → AGENTS.md"]
    D --> E["CLAUDE.md를 AGENTS.md에 링크<br>.claude를 .agents에 링크"]
    E --> F["스크립트 자체를 삭제"]
```

## 설치 후의 GitHub 설정

README에 기재된 설치 후의 권장 설정:

* **Dependabot PR은 수동 리뷰** — 자동 머지 워크플로우는 포함되지 않음
* **릴리스 노트 라벨 작성** — `breaking` · `enhancement` · `bug` · `documentation` · `dependencies` · `maintenance` · `skip-changelog` · `duplicate`
* **`main` 브랜치 보호 설정** — Changelog 자동화는 GitHub Actions가 `CHANGELOG.md`에 커밋하므로, 브랜치 보호 룰의 조정이 필요

추가 리포지토리 시크릿은 불필요합니다. 포함된 워크플로우는 GitHub의 내장 `GITHUB_TOKEN`을 사용합니다.

## 현재의 개발 상황

* **GitHub 리포지토리**: [laravel/package-skeleton](https://github.com/laravel/package-skeleton)
* **공개 시기**: 2026년 7월 (활발히 개발 중)
* **주의**: 개발 초기 단계이므로 API나 구성이 변경될 가능성이 있습니다

이제부터 Laravel 패키지를 만들기 시작하는 분은, 자기 방식의 스켈레톤을 처음부터 조립하기보다 이 템플릿에서 시작하는 것이 좋습니다. Laravel 팀이 오랜 세월의 패키지 개발에서 얻은 베스트 프랙티스가 담겨 있습니다.

<Card title="laravel/package-skeleton 리포지토리" icon="github" href="https://github.com/laravel/package-skeleton">
  소스 코드와 최신 정보는 이곳에서 확인하실 수 있습니다.
</Card>

<Card title="패키지 개발 공식 문서" icon="book-open" href="https://laravel.com/docs/packages">
  Laravel 패키지 개발의 기초에 대해서는 공식 문서를 참고하세요.
</Card>


## Related topics

- [Laravel 스타터 킷 만드는 법](/ko/advanced/starter-kit-creation.md)
- [스타터 킷](/ko/starter-kits.md)
- [Laravel Fortify와 스타터 킷](/ko/advanced/fortify.md)
- [Laravel Chisel — 스타터 킷의 포스트 인스톨 스크립트 라이브러리](/ko/blog/chisel-introduction.md)
- [Vue.js 입문 — Inertia × Laravel에서 사용하는 기초 지식](/ko/blog/vue-introduction.md)