스타터 킷

Laravel의 스타터 킷을 사용해 인증·UI를 빠르게 세팅하는 방법

​

스타터 킷이란

스타터 킷은 Laravel 애플리케이션의 출발점으로 준비된 공식 스캐폴딩입니다. 로그인·등록·비밀번호 재설정·이메일 확인 같은 인증 기능과 그에 대응하는 UI를 한꺼번에 세팅할 수 있습니다.

laravel new로 애플리케이션을 생성할 때 스타터 킷을 선택하는 것만으로 인증 주변의 라우트·컨트롤러·뷰·프런트엔드 코드가 모두 자동으로 생성됩니다. 생성된 코드는 모두 자신의 애플리케이션 내에 존재하므로 자유롭게 커스터마이징할 수 있습니다.

Laravel 13에서는 기존의 Breeze와 Jetstream은 폐지되었습니다. 새 프로젝트에서는 아래에 소개하는 스타터 킷을 사용해 주세요. 기존 Breeze나 Jetstream을 사용한 프로젝트는 그대로 동작하지만, 신규 개발에는 권장되지 않습니다.

​

이용 가능한 스타터 킷

Laravel 13에서는 다음 4종류의 스타터 킷이 제공됩니다.

React

React 19·TypeScript·Tailwind 4·shadcn/ui를 사용한 모던한 SPA. Inertia.js로 서버사이드 라우팅을 유지하면서 React를 사용할 수 있습니다.

Vue

Vue 3 Composition API·TypeScript·Tailwind·shadcn-vue를 채택. React와 마찬가지로 Inertia.js로 서버사이드와 연동합니다.

Livewire

PHP만으로 동적 UI를 구축할 수 있는 Livewire. Blade 템플릿 중심의 팀이나 JavaScript 프레임워크를 사용하지 않으려는 경우에 최적입니다. Flux UI를 채택.

Svelte

Svelte 5·TypeScript·Tailwind·shadcn-svelte를 사용한 SPA. Inertia.js와 조합해 모던한 프런트엔드를 구축할 수 있습니다.

​

어떤 것을 선택할지

스타터 킷	적합한 팀
React	React 에코시스템이나 TypeScript에 익숙한 팀
Vue	Vue나 Nuxt 경험이 있는 팀
Livewire	PHP와 Blade를 중심으로 개발하고 싶은 팀
Svelte	Svelte나 SvelteKit 경험이 있는 팀

어느 것을 선택하든 인증 기능은 완전히 동일합니다. 팀이 가장 익숙한 프런트엔드 기술을 선택해 주세요.

Blade·Livewire·Inertia·독립 SPA의 차이를 전체적으로 확인하고 싶은 경우, 먼저 프런트엔드를 읽으면 선택하기 쉬워집니다.

​

설치 방법

스타터 킷은 프로젝트 생성 시에 선택합니다. laravel new 명령을 실행하면 대화형으로 스타터 킷을 선택할 수 있습니다.

1. Laravel 인스톨러를 설치한다

   아직 설치하지 않은 경우, Composer로 Laravel 인스톨러를 취득합니다.

   composer global require laravel/installer
   
2. 새 애플리케이션을 생성한다

   laravel new 명령을 실행합니다. 스타터 킷 선택을 포함한 대화형 프롬프트가 표시됩니다.

   laravel new my-app
   

   프롬프트에서 React, Vue, Livewire, Svelte 중 하나를 선택합니다. 인증 프로바이더로 표준 Laravel 인증 또는 WorkOS AuthKit도 선택할 수 있습니다.

3. 프런트엔드 의존 관계를 설치한다

   cd my-app
   npm install && npm run build
   
4. 데이터베이스를 준비한다

   .env 파일의 데이터베이스 설정을 확인한 후 마이그레이션을 실행합니다.

   php artisan migrate
   
5. 개발 서버를 기동한다

   composer run dev
   

   브라우저에서 http://localhost:8000에 접속하면 내비게이션에 “Register”와 “Log in” 링크가 표시됩니다.

스타터 킷을 설치하면 다음 인증 기능을 즉시 사용할 수 있습니다.

기능	URL
사용자 등록	/register
로그인	/login
비밀번호 재설정	/forgot-password
이메일 확인	/email/verify
프로필 편집	/settings/profile

​

스타터 킷 커스터마이징

생성된 코드는 모두 자신의 애플리케이션 내에 있으므로 자유롭게 변경할 수 있습니다. 프런트엔드 코드의 대부분은 resources/js(Livewire는 Blade이므로 resources/views) 디렉터리에 있습니다.

​

레이아웃 전환

각 스타터 킷에는 “사이드바”와 “헤더” 두 종류의 레이아웃이 준비되어 있습니다. 기본값은 사이드바 레이아웃입니다.

React

resources/js/layouts/app-layout.tsx를 편집합니다.

// 사이드바 레이아웃(기본값)
import AppLayoutTemplate from '@/layouts/app/app-sidebar-layout';

// 헤더 레이아웃으로 변경할 경우
import AppLayoutTemplate from '@/layouts/app/app-header-layout';

Vue

resources/js/layouts/AppLayout.vue를 편집합니다.

// 사이드바 레이아웃(기본값)
import AppLayout from '@/layouts/app/AppSidebarLayout.vue';

// 헤더 레이아웃으로 변경할 경우
import AppLayout from '@/layouts/app/AppHeaderLayout.vue';

Livewire

resources/views/layouts/app.blade.php를 편집합니다.

{{-- 헤더 레이아웃으로 변경할 경우 --}}
<x-layouts::app.header>
    <flux:main container>
        {{ $slot }}
    </flux:main>
</x-layouts::app.header>

Svelte

resources/js/layouts/AppLayout.svelte를 편집합니다.

// 사이드바 레이아웃(기본값)
import AppLayout from '@/layouts/app/AppSidebarLayout.svelte';

// 헤더 레이아웃으로 변경할 경우
import AppLayout from '@/layouts/app/AppHeaderLayout.svelte';

​

인증 페이지의 레이아웃 변경

로그인이나 등록 페이지도 “simple”, “card”, “split” 세 종류의 레이아웃에서 선택할 수 있습니다.

React

resources/js/layouts/auth-layout.tsx를 편집합니다.

// 심플 레이아웃(기본값)
import AuthLayoutTemplate from '@/layouts/auth/auth-simple-layout';

// 분할 레이아웃으로 변경할 경우
import AuthLayoutTemplate from '@/layouts/auth/auth-split-layout';

Vue

resources/js/layouts/AuthLayout.vue를 편집합니다.

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.vue';

// 분할 레이아웃으로 변경할 경우
import AuthLayout from '@/layouts/auth/AuthSplitLayout.vue';

Livewire

resources/views/layouts/auth.blade.php를 편집합니다.

<x-layouts::auth.split>
    {{ $slot }}
</x-layouts::auth.split>

Svelte

resources/js/layouts/AuthLayout.svelte를 편집합니다.

import AuthLayout from '@/layouts/auth/AuthSimpleLayout.svelte';

// 분할 레이아웃으로 변경할 경우
import AuthLayout from '@/layouts/auth/AuthSplitLayout.svelte';

​

사용자 등록 로직의 커스터마이징

스타터 킷은 사용자 등록이나 비밀번호 재설정 처리에 app/Actions/Fortify 디렉터리의 액션 클래스를 사용합니다. 예를 들어 등록 시에 전화번호 필드를 추가하려면 CreateNewUser.php를 편집합니다.

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을 선택할 수도 있습니다. WorkOS AuthKit을 사용하면 다음 기능이 추가됩니다.

• 소셜 인증(Google·Microsoft·GitHub·Apple)
• 패스키 인증
• 이메일에 의한 “Magic Auth”
• SSO(싱글 사인온)

WorkOS AuthKit 이용에는 WorkOS 계정이 필요합니다. 월간 활성 사용자 100만 명까지는 무료로 이용할 수 있습니다.

WorkOS를 선택한 경우 .env 파일에 다음 환경 변수를 설정합니다.

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

​

주의점

스타터 킷은 프로젝트 생성 시에 선택하는 것입니다. 기존 프로젝트에 나중에 추가할 수는 없습니다. 인증 UI가 필요한 경우, 신규 프로젝트에서 스타터 킷을 선택하거나 수동으로 인증 기능을 구현해 주세요.

​

다음 단계

인증 입문

Auth 파사드의 사용법이나 라우트의 보호 등 Laravel의 인증 기능을 더 자세히 배웁니다.