Laravel SailとLaravel BreezeでLaravel+Next.jsのフルスタック開発環境を構築する（git設定まで）【Windows11】

Laravel + Next.jsのフルスタック開発環境の構築手順について解説します。
バックエンドには、Laravel Sailを用いてLaravelの環境を構築し、Laravel Breezeも導入しました。
フロントエンドには、Laravel Breeze – Next.js Editionを使用し、Next.jsの環境を構築しました。

実現したいこと

本記事では、以下の手順でLaravel + Next.jsの開発環境を構築します。

1. Laravelの環境構築（Laravel Sailを使用）
2. Laravel Breezeの導入（認証機能の実装）
3. Next.jsの環境構築（Laravel Breezeと連携するため、Laravel Breeze – Next.js Editionを使用）

Laravel Sailとは

Laravel Sailとは、Laravelプロジェクトを開発するための軽量なDocker環境を簡単にセットアップするためのツールです。

主な特徴：

• コマンドを実行するだけでLaravelの環境構築が可能
• MySQLやmailpitなどの必要なサービスをコンテナとして自動で構築
• Laravelの開発に必要なComposerなどのインストールや初期設定も一括でやってくれる

Laravel Breezeとは

Laravel Breezeとは、アカウント登録、ログイン、パスワードリセットなどの基本的な認証機能を簡単に導入できる軽量なパッケージです。
Breeze を使うことで、Laravel 内に認証機能の骨組みを数分で構築できます。

Next.jsやNuxtと連携できるAPIベースの認証機能も提供できます。
Laravelが管理するLaravel Breeze – Next.js Editionを使用すると、Breezeが提供する従来の Blade および Inertia スタックと同じUIをNext.jsで実現できます。

なので、LaravelがバックエンドAPIを担当、Next.jsがフロントエンドを担当というように、完全に役割を分けて開発することができます。

実行環境（OSや各種バージョンなど）

今回、試した環境は、以下のとおりです。

ディレクトリ構成

以下のようなディレクトリ構成で、環境構築を進めていきます。

my-app/（ルートディレクトリ）
├ server/
└ client/

Laravelの環境構築

Laravel公式サイトの説明に沿って、Laravelの環境を準備していきます。

参考

Installation – Laravel 11.x – The PHP Framework For Web Artisans

事前準備

本記事では解説しませんが、事前に以下の準備をしておきます。

• Dockerデスクトップのインストール・起動
• WSL2（Ubuntu）のインストール・起動

Laravelのインストール

Ubuntuターミナルを起動して、cdコマンドでプロジェクトファイルを配置するディレクトリに移動します。
※ディレクトリのパスは、ご自身の環境に合わせて変更してください。

/mnt/c/UsersがWindows上のC:\Usersを指します。

cd /mnt/c/Users/[ユーザー名]/my-app

以下のコマンドでLaravelプロジェクトを作成します。
※[プロジェクト名]は任意で決めてください。（以降はserverとして説明を進めます）

curl -s https://laravel.build/[プロジェクト名] | bash

私の環境では、10分くらいで処理が終わって、最後にパスワードを求められました。

[sudo] password for ubuntu:

パスワードを入力すると以下のメッセージが表示されて完了しました。

Thank you! We hope you build something incredible. Dive in with: cd server && ./vendor/bin/sail up

指定したプロジェクト名（今回はserver）のディレクトリが作成され、その配下にLaravel関連のファイルが生成されていると思います。

$ ls server/
README.md      composer.lock       phpunit.xml        storage
app            config              postcss.config.js  tailwind.config.js   
artisan        database            public             tests
bootstrap      docker-compose.yml  resources          vendor
composer.json  package.json        routes             vite.config.js 

Dockerの起動

プロジェクトディレクトリに移動して、sailで立ち上げてみます。

cd server/

./vendor/bin/sail up -d

このときに、下記のエラーが出たので、参考記事を見ながら対処しました。

Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:3306 -> 0.0.0.0:0: listen tcp 0.0.0.0:3306: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

参考

ポートが別のプロセスによって使用されている時

ポート番号の設定

環境変数にポート番号の設定を追加しておきます。
.envに以下の記述を追加します。
もしAPP_PORTがすでに存在する場合は、8000に変更してください。

APP_PORT=8000

Laravel Breezeを導入すると、Laravelのポート番号8000とNext.jsのポート番号3000で通信するようになります。
しかし、APP_PORTを指定しないとポート番号80でLaravelアプリケーションが立ち上がってしまうので、設定しておきます。

マイグレーション

Dockerが起動できたら、下記のコマンドでマイグレーションを実行します。

./vendor/bin/sail artisan migrate

動作確認

ブラウザでhttp://localhost:8000/にアクセスして、下記のようにLaravelのバージョンが表示されたら成功です。

phpMyAdminの設定

Laravel sailにはphpMyAdminの設定がないので、追加しておきたいと思います。

sailを止めておきます。

./vendor/bin/sail down

server/直下にあるdocker-compose.ymlに、下記ハイライト部分を追記します。

services:
    laravel.test:
    ～～ 省略 ～～

    mysql:

    ～～ 省略 ～～

    phpmyadmin:
        image: phpmyadmin/phpmyadmin
        links:
            - mysql:mysql
        ports:
            - 8080:80
        environment:
            MYSQL_USERNAME: "${DB_USERNAME}"
            MYSQL_ROOT_PASSWORD: "${DB_PASSWORD}"
            PMA_HOST: mysql
        networks:
            - sail

    redis:

    ～～ 省略 ～～

もう一度sailを立ち上げます。

./vendor/bin/sail up -d

ブラウザでhttp://localhost:8080/にアクセスして、下記のようにphpMyAdminのページが表示されたらOKです。

ユーザ名とパスワードは、それぞれ以下のものを使用するとログインできます。

タイムゾーンの設定

デフォルトだとタイムゾーンがUTCになっているので、日本時間に設定します。
環境変数（.env）にタイムゾーンの設定があるので、'UTC'から'Asia/Tokyo'に変更すればOKです。

APP_TIMEZONE=Asia/Tokyo

日本語化

フロントエンドはすべてNext.jsで実装しますが、メール送信などはLaravelから行われるので、翻訳パッケージをインストールして日本語化しておきます。

まずは、英語の翻訳ファイルをインストールします。
プロジェクトディレクトリ直下に、lang/en/のディレクトリが作成され、英語の翻訳ファイルが作成されます。

./vendor/bin/sail artisan lang:publish

以下のリポジトリで日本語の翻訳ファイルが公開されているので、インストールして利用します。

Laravel Sail用のコマンドも記載があるので、その通りにコマンドを実行すればOKです。

参考

Laravel Breeze 日本語化パッケージ：Breezejp

英語の翻訳ファイルと同様、lang/jpというディレクトリが作成され、日本語の翻訳ファイルが作成されます。

Laravel Breezeの導入

Laravel公式サイトの説明に沿って、Laravel Breezeを導入していきます。

参考

Starter Kits – Laravel 11.x – The PHP Framework For Web Artisans

Laravelの環境が起動している状態で、Laravel環境のルートディレクトリ（server/）でコマンドを実行していきます。

インストール

以下のコマンドを実行します。

./vendor/bin/sail composer require laravel/breeze --dev

完了したら、以下のコマンドで、Laravel Breezeのセットアップを行います。

./vendor/bin/sail artisan breeze:install

選択を求められるので、API onlyを選んで、以下のように進めました。
マイグレーションについても確認があり、「yes」を選びました。

$ ./vendor/bin/sail artisan breeze:install

 ┌ Which Breeze stack would you like to install? ───────────────┐
 │ API only                                                     │
 └──────────────────────────────────────────────────────────────┘

 ┌ Which testing framework do you prefer? ──────────────────────┐
 │ Pest                                                         │
 └──────────────────────────────────────────────────────────────┘

～～　省略　～～

 One new database migration has been published. Would you like to run all pending database migrations? (yes/no) [yes]:
 > yes

以下のようなメッセージが表示されて完了しました。

   INFO  Breeze scaffolding installed successfully.

Next.jsの環境構築

Next.jsの環境は、https://github.com/laravel/breeze-nextからクローンして構築していきます。
バックエンドは、WSL（Ubuntuターミナル）でコマンドを実行していましたが、フロントエンドは、Windowsのターミナルで実行します。（WSLでも問題はないはず。。）

Next.jsプロジェクトの作成

ルートディレクトリに戻って、ソースコードをクローンします。
※[プロジェクト名]は任意で決めてください。（以降はclientとして説明を進めます）

git clone https://github.com/laravel/breeze-next.git [プロジェクト名]

プロジェクトのディレクトリに移動して、依存関係をインストールします。

cd client
npm i

.env.localの作成

.env.exampleをコピーして、.env.localを作成しておきます。

cp .env.example .env.local

TypeScriptへの変換

クローンしてきたNext.jsのプロジェクトはJavaScriptで記述されているので、TypeScriptに変換します。

パッケージのインストール

必要なパッケージをインストールします。

npm install --save-dev typescript @types/react @types/node  @typescript-eslint/parser @typescript-eslint/eslint-plugin

ESLintの設定を変更

.eslintrc.jsの設定を３か所変更します。

①TypeScript のコードを正しく解析するために、@typescript-eslint/parser を使用するように設定します。

parser: '@typescript-eslint/parser',

②TypeScript 用のルールを ESLint に追加するために、plugin:@typescript-eslint/recommended を extends に追加します。

extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:@next/next/recommended',
    'prettier',
    'plugin:@typescript-eslint/recommended',      // 追加
],

③.tsx 拡張子でも JSX を使えるように、react/jsx-filename-extension ルールを変更します。

rules: {
    ～～　省略　～～
    'react/jsx-filename-extension': [
        1,
        { extensions: ['.js', '.jsx', '.ts', '.tsx'] },
    ],
    ～～　省略　～～
},

ファイル名の変更

jsconfig.jsonをtsconfig.jsonにリネームします。

mv jsconfig.json tsconfig.json

拡張子をjsからtsやtsxに変更します。

mv ./src/hooks/auth.js ./src/hooks/auth.ts
mv ./src/lib/axios.js ./src/lib/axios.ts
find ./src/ -type f -name "*.js" -exec bash -c 'mv "$0" "${0%.js}.tsx"' {} \;

プロジェクトの起動とコードの修正

プロジェクトを起動します。
このときに、tsconfig.jsonの中身が記述され、next-env.d.tsが追加されます。

npm run dev

TypeScriptに変換したことにより、型チェックが入るので、必要に応じてコードを修正します。

動作確認

プロジェクトが起動していない場合は、起動しておきます。

npm run dev

ブラウザでhttp://localhost:3000/にアクセスして、下記のようにLaravelのページが表示されたら成功です。

画面右下に、「Laravel Breeze + Next.js template」とあり、Laravel BreezeとNext.jsが連携した画面であることがわかります。

アカウント登録＋メール認証、ログイン、ログアウト、パスワード変更など、認証機能がすでに利用できるはずなので、実際に操作して確認してみてください。

メール認証やパスワード変更などでは、指定したメールアドレス宛にメールが送信され、そのメールに記載のあるリンクをクリックして動作確認することになります。

Laravel Sailの環境には、ローカル開発用のメールサービス「Mailpit」が含まれているので、これを使用して動作確認ができます。
ブラウザでhttp://localhost:8025/にアクセスした状態で、メール認証やパスワード変更を試すと、宛先のメールアドレスに関係なく、mailpitの受信ボックスにメールが届きます。

git設定

ルートディレクトリ全体を１つのgitリポジトリとして管理したいので、整理していきます。
PowerShellだとコマンドが動作しなかったので、以降は、Git Bashでコマンド操作していきます。

.gitの削除

ルートディレクトリでfindコマンドを実行すると、client/配下に.gitディレクトリが存在していることが確認できます。

$ find . -type d -name .git
./client/.git

.gitディレクトリを削除します。

rm -rf ./client/.git

.gitignoreファイルなども存在しますが、そのままにしておきます。
ルートディレクトリをgit管理にしたときに、.gitignoreがそのまま適用されます。

ルートディレクトリにgitリポジトリを作成する

以下のコマンドで、ルートディレクトリにgitリポジトリを作成します。

git init

これでルートディレクトリをgit管理にすることができました。
あとは、README.mdファイルを追加したり、githubなどに登録したりして利用してください。

Haruna Abe

Webエンジニア

X

フロントエンドエンジニア２年目｜ReactやTypeScriptなど、フロントエンドの情報を発信していきます