라라벨 13에 Laravel Breeze 설치하기 (Could not resolve './bootstrap' in resources/js/app.js 에러 해결 방법)

라라벨 12의 업데이트가 너무 마음에 들지 않아서 라라벨 12는 사용해 본 적이 없다.

라라벨 12 때에도 계속 라라벨 11만 사용하고 있었다.

그런데 이번에 블로그 포스팅을 위해 그래도 최신 버전을 다뤄야겠다는 생각이 들어서 13을 설치했고, 거기에 Laravel Breeze를 설치하려고 했다.

그 과정에서 발생한 에러를 해결하는 과정을 공유하려고 한다.

이전 포스트

Permission Denied 에러 해결 및 생성 파일 권한 자동 설정하기

Docker 환경에서 Permission Denied 에러가 발생하는 이유(컨테이너의 root 소유권)를 설명하고, chown 명령어를 이용한 수동 해결 방법과 Makefile을 이용하여 컨테이너 내에서 생성되는 파일의 소유권을 자동으로 설정하는 방법을 알려드립니다.

라라벨 브리즈란?

라라벨 브리즈^{Laravel Breeze}는 '라라벨 인증 스타터 키트'다.

웹사이트를 만들 때 가장 먼저 필요한 기능이 로그인, 회원가입, 비밀번호 찾기 같은 인증(Authentication) 기능이다.

이걸 일일이 코드로 짜려면 시간이 꽤 걸린다.

브리즈는 이 모든 필수 기능을 라라벨의 표준 방식(MVC 패턴)으로 미리 짜서 제공해 주는 도구다.

라라벨 브리즈를 설치하면, '로그인 & 회원가입 페이지', '비밀번호 재설정', '마이페이지 (정보 수정 및 회원 탈퇴)' 등의 기능이 바로 뚝딱 만들어진다.

Laravel Breeze 설치하기

이전 포스트까지 다뤘던 Laravel을 설치하고 Makefile을 만드는 것까지 완료했다면, 다음의 명령어들을 차례대로 실행하자.

make app #컨테이너 안으로 들어간다. make bash로 들어가서 설치할 경우 에러가 발생한다.
composer require laravel/breeze --dev
php artisan breeze:install

설치 명령어를 입력하면, 이렇게 몇 가지 질문들과 선택지들이 나온다.

1. Which Breeze stack would you like to install?

어떤 프런트엔드 기술을 사용할지에 따라 다양한 '스택(Stack)'을 제공한다.

캡처한 이미지의 옵션들을 간단히 설명하자면 다음과 같다.

• Blade with Alpine: 라라벨의 전통적인 템플릿 엔진인 Blade를 사용한다. php 중심의 개발을 선호하고, 자바스크립트는 최소한(모달창, 드롭다운 등)으로만 사용하고 싶을 때 가장 좋다. 가장 학습 곡선이 낮고 가볍다.
• Livewire with Alpine: 자바스크립트를 거의 쓰지 않고도 php만으로 동적인 화면(새로고침 없는 검색, 버튼 클릭 등)을 만들 수 있는 도구다. Class API와 Volt Functional API의 차이는 다음에 Livewire에 대해서 다룰 때 다시 설명하도록 하겠다.
• React / Vue with Inertia: 강력한 자바스크립트 프레임워크인 React나 Vue를 사용한다. 중간에 Inertia.js가 끼어있어, 라라벨 라우팅을 그대로 쓰면서도 Single Page Application(SPA)처럼 부드럽게 작동한다. Inertia.js를 사용하지 않고 React나 Vue만 사용할 거라면 이 옵션을 선택하지 말고 다른 방법을 써야 한다.
• API only: 화면(뷰)은 전혀 만들지 않고, 로그인/회원가입 기능이 있는 백엔드 API 서버만 구축합니다. 별도의 모바일 앱(아이폰, 안드로이드)이나 독립적인 프런트엔드 프로젝트(Next.js 등)와 통신할 서버만 필요할 때 사용한다.

2. Would you like dark mode support?

다크 모드를 지원하는 웹사이트를 만들거라면, 'Yes',

'나는 밝은 테마만 고집하겠다'라면, 'No'를 선택한다.

Yes를 선택하면, Tailwind CSS의 dark: 클래스가 포함된 Blade 파일들이 생성돼서 다크 모드 설정을 하기 편해진다.

3. Which testing framework do you prefer?

테스트 프레임워크를 뭘 사용할지 결정하는 것이다.

Pest와 PHPUnit 중에 선택해야 하는데, 뭘 선택해야 할지 모르겠다면 현재 대세인 Pest를 선택하자.

원래대로라면 Laravel Breeze가 문제없이 잘 설치되고, 여기서 포스팅이 끝나야 하는데..

Laravel 13에서 브리즈를 설치하려고 하니 뭔가 문제가 생겼다.

Could not resolve './bootstrap' in resources/js/app.js

잘 설치되는 듯하다가 마지막쯤에 이런 에러가 떴다.

✗ Build failed in 413ms
error during build:
Build failed with 1 error:

[UNRESOLVED_IMPORT] Error: Could not resolve './bootstrap' in resources/js/app.js
   ╭─[ resources/js/app.js:1:8 ]
   │
 1 │ import './bootstrap';
   │        ──────┬──────
   │              ╰──────── Module not found.
───╯

이 에러 메시지가 뜬 이유는 아래의 이미지와 함께 설명하도록 하겠다.

resources/js/app.js 파일의 첫 줄을 보니 import './bootstrap';이라고 되어 있는데, 정작 같은 폴더 안에 있어야 할 bootstrap.js 파일이 없어서 이런 메시지가 뜬 것이다.

검색을 해보니, Laravel 13에는 더 이상 bootstrap.js가 포함되지 않는다고 한다.

그런데 app.js에서 이를 임포트하려고 시도한다.

그래서 npm install 과정에서 오류가 발생하는 것이다.

resources/js/bootstrap.js

import axios from 'axios';
window.axios = axios;

window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

resources/js/bootstrap.js 파일을 수동으로 추가하자.

코드는 이전 버전의 Laravel에 있던 bootstrap.js 파일의 코드를 그대로 가져왔다.

혹시 axios를 이용한 비동기 통신이나 복잡한 자바스크립트 설정을 직접 건드릴 계획이 없다면, bootstrap.js 파일을 만들지 않고 app.js 파일의 첫 줄을 삭제하거나 주석 처리하면 된다.

나는 bootstrap.js 파일을 만들기로 했다.

나중에 '좋아요' 버튼 기능을 구현할 때, axios를 이용한 비동기 통신이 필요하기 때문이다. (필수는 아니지만)

make app #컨테이너 안으로 들어간다.
npm install axios
npm run dev

여기까지 했으면 마지막으로 VSCode의 터미널에서 이 명령어들을 실행해주자.

npm install axios는 이번 한 번만 실행하지만, npm run dev는 앞으로 개발을 할 때, 항상 VSCode의 터미널에서 php 컨테이너 안으로 들어간 다음에 실행하게 될 명령어다.

그리고 http://localhost/ 에 접속하면 Laravel Breeze가 설치된 첫 페이지가 표시돼야 하는데, Windows 운영체제의 경우에는 화면의 스타일이 깨져서 이상하게 출력이 된다.

이 문제에 대한 해결 방법은 다음 포스트에 정리하도록 하겠다.

다음 포스트

Windows 도커 환경에서 Laravel Breeze CSS 깨짐 해결법 (WSL2에서 Vite 개발 서버를 실행할 때)

Windows 도커 환경에서 Laravel Breeze 설치 후 CSS 스타일이 깨지는 현상을 해결하는 가이드입니다. WSL2 환경의 Vite 개발 서버가 브라우저와 정상적으로 통신할 수 있도록 파일들을 수정하는 구체적인 방법을 정리했습니다.