Installation

This guide provides detailed instructions for setting up Laravel Breeze API + Next.js in your development environment.

Prerequisites

Before you begin, ensure your system meets these requirements:

Required Software

PHP 8.2 or higher - Verify with php --version
Composer - PHP dependency manager (Download)
Node.js 18+ - JavaScript runtime (Download)
npm or pnpm - Package manager (pnpm recommended)
Git - Version control

Database Options

SQLite - Default for development (no installation required)
MySQL 5.7+ or MariaDB 10.3+ (Optional)
PostgreSQL 10+ (Optional)

Verify Installation

Check that all required tools are installed:

php --version
composer --version
node --version
npm --version
git --version

Backend Setup (Laravel)

1. Clone the Repository

First, clone the repository and navigate to the project directory:

git clone <your-repository>
cd LaravelBreezeApi_Nextjs

2. Install Backend Dependencies

Navigate to the Backend directory and install PHP dependencies:

cd Backend
composer install

This will install:

Laravel Framework 12.x
Laravel Sanctum 4.x
Laravel Breeze 2.x
Pest PHP testing framework
Other required packages

3. Environment Configuration

Copy the example environment file and generate an application key:

cp .env.example .env
php artisan key:generate

4. Configure Environment Variables

Open the .env file and configure the following settings:

Basic Application Settings

APP_NAME="Laravel Breeze API"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

Frontend URL Configuration

This is crucial for CORS to work properly:

FRONTEND_URL=http://localhost:3000
SANCTUM_STATEFUL_DOMAINS=localhost:3000

Database Configuration

SQLite (Recommended for Development)
MySQL
PostgreSQL

DB_CONNECTION=sqlite
# DB_DATABASE=/absolute/path/to/database.sqlite

Create the SQLite database file:

touch database/database.sqlite

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=backend
DB_USERNAME=root
DB_PASSWORD=

Create the database:

mysql -u root -p
CREATE DATABASE backend;
exit;

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=backend
DB_USERNAME=postgres
DB_PASSWORD=

Create the database:

psql -U postgres
CREATE DATABASE backend;
\q

Session and Cache Configuration

SESSION_DRIVER=database
SESSION_LIFETIME=120

CACHE_STORE=database
QUEUE_CONNECTION=database

Mail Configuration (for Password Reset)

Log (Development)
SMTP (Production)

MAIL_MAILER=log
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Emails will be logged to storage/logs/laravel.log

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

5. Run Database Migrations

Create the database tables:

php artisan migrate

This creates tables for:

Users
Password resets
Sessions
Cache
Jobs queue
Personal access tokens (Sanctum)

6. (Optional) Seed the Database

Populate the database with sample data:

php artisan db:seed

7. Configure CORS

The CORS configuration is located at config/cors.php. By default, it’s configured to accept requests from your frontend:

'paths' => ['*'],
'allowed_methods' => ['*'],
'allowed_origins' => [env('FRONTEND_URL', 'http://localhost:3000')],
'allowed_headers' => ['*'],
'supports_credentials' => true,

Make sure supports_credentials is set to true for Sanctum authentication to work properly.

8. Verify Backend Installation

Start the Laravel development server:

php artisan serve

Visit http://localhost:8000 to verify the backend is running. Test the API endpoint:

curl http://localhost:8000/api/user

You should receive a 401 Unauthorized response (expected, as you’re not authenticated).

Frontend Setup (Next.js)

1. Navigate to Frontend Directory

Open a new terminal and navigate to the Frontend directory:

cd Frontend

2. Install Frontend Dependencies

pnpm (Recommended)
npm
yarn

pnpm install

npm install

yarn install

This installs:

Next.js 16.x
React 19.x
TypeScript 5.x
Tailwind CSS 4.x
Headless UI
Formik & Yup
Axios & SWR
Other dependencies

3. Configure Environment Variables

Create a .env.local file in the Frontend directory:

cp .env.example .env.local

Edit .env.local and set the backend URL:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

The NEXT_PUBLIC_ prefix makes this variable accessible in the browser.

4. Verify Frontend Configuration

The frontend is configured to work with the backend through the NEXT_PUBLIC_BACKEND_URL environment variable. All API calls will be made to this URL. Key configuration files:

src/lib/axios.ts - Axios configuration for API calls
src/hooks/auth.ts - Authentication hooks
tailwind.config.ts - Tailwind CSS configuration
next.config.js - Next.js configuration

5. Run Frontend Development Server

pnpm
npm
yarn

pnpm dev

npm run dev

yarn dev

The frontend will be available at http://localhost:3000.

Running Both Applications

Option 1: Automated (Recommended)

From the Backend directory, run:

composer run dev

This executes a script defined in composer.json that runs:

Laravel server on port 8000
Queue worker for background jobs
Next.js development server on port 3000

All processes run in parallel using concurrently.

Option 2: Manual

Run each service in a separate terminal: Terminal 1 - Laravel Server:

cd Backend
php artisan serve

Terminal 2 - Queue Worker:

cd Backend
php artisan queue:listen

Terminal 3 - Next.js Server:

cd Frontend
pnpm dev

Testing the Installation

1. Test Backend API

With the backend running, test the user endpoint:

curl -X GET http://localhost:8000/api/user \
  -H "Accept: application/json"

Expected response: {"message":"Unauthenticated."}

2. Test Frontend

Visit http://localhost:3000
You should see the login page
Click “Register” to create a new account
Fill out the registration form:
- Name
- Email
- Password
- Confirm Password
Submit the form

3. Test Authentication Flow

After registration:

You should be automatically logged in
The dashboard page should load
Your user information should be displayed
Try logging out and logging back in

4. Test Password Reset (Optional)

Click “Forgot Password” on the login page
Enter your email address
Check storage/logs/laravel.log for the reset link
Follow the link to reset your password

Running Tests

Backend Tests

Run the Pest test suite:

cd Backend

# Run all tests
composer test

# Run specific test suite
php artisan test --testsuite=Feature

# Run specific test file
php artisan test tests/Feature/Auth/RegistrationTest.php

# Run with coverage
php artisan test --coverage

Frontend Linting

cd Frontend
pnpm lint

Production Build

Backend Production Setup

cd Backend

# Install production dependencies only
composer install --no-dev --optimize-autoloader

# Optimize configuration
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Run migrations
php artisan migrate --force

Update .env for production:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com
FRONTEND_URL=https://app.yourdomain.com

Frontend Production Build

cd Frontend

# Build the application
pnpm build

# Test production build locally
pnpm start

Update .env.local for production:

NEXT_PUBLIC_BACKEND_URL=https://api.yourdomain.com

Production Checklist:

Enable HTTPS for both frontend and backend
Update APP_URL and FRONTEND_URL to production URLs
Set APP_DEBUG=false
Use a production database (MySQL/PostgreSQL)
Configure proper mail settings
Set up proper session and cache drivers (Redis recommended)
Configure queue workers with Supervisor
Set up proper logging and monitoring

Troubleshooting

CORS Issues

Symptom: “CORS policy” errors in browser console Solution:

Verify FRONTEND_URL in backend .env matches your frontend URL
Ensure config/cors.php has 'supports_credentials' => true
Clear config cache: php artisan config:clear
Restart the backend server

419 CSRF Token Mismatch

Symptom: 419 error when submitting forms Solution:

Verify SANCTUM_STATEFUL_DOMAINS includes your frontend domain
Ensure cookies are being sent with requests
Check that withCredentials is set in Axios configuration

Database Connection Errors

Symptom: “Could not find driver” or connection refused errors Solution:

For SQLite: Ensure php-sqlite3 extension is installed
For MySQL: Install php-mysql extension
For PostgreSQL: Install php-pgsql extension
Verify database credentials in .env
Ensure database exists

Port Already in Use

Symptom: “Address already in use” error Solution:

# Use different port for backend
php artisan serve --port=8001

# Use different port for frontend
pnpm dev -- -p 3001

Update environment variables accordingly.

Module Not Found Errors

Symptom: Frontend shows “Module not found” errors Solution:

# Clear node_modules and reinstall
rm -rf node_modules
rm pnpm-lock.yaml  # or package-lock.json for npm
pnpm install

Next Steps

Now that your installation is complete:

Explore the codebase structure
Review the authentication implementation
Start building your application features
Check out the Laravel Documentation
Read the Next.js Documentation
Learn about Laravel Sanctum

Get Started

Core Concepts

Backend Guide

Frontend Guide

Deployment

​Installation

​Prerequisites

​Required Software

​Database Options

​Verify Installation

​Backend Setup (Laravel)

​1. Clone the Repository

​2. Install Backend Dependencies

​3. Environment Configuration

​4. Configure Environment Variables

​Basic Application Settings

​Frontend URL Configuration

​Database Configuration

​Session and Cache Configuration

​Mail Configuration (for Password Reset)

​5. Run Database Migrations

​6. (Optional) Seed the Database

​7. Configure CORS

​8. Verify Backend Installation

​Frontend Setup (Next.js)

​1. Navigate to Frontend Directory

​2. Install Frontend Dependencies

​3. Configure Environment Variables

​4. Verify Frontend Configuration

​5. Run Frontend Development Server

​Running Both Applications

​Option 1: Automated (Recommended)

​Option 2: Manual

​Testing the Installation

​1. Test Backend API

​2. Test Frontend

​3. Test Authentication Flow

​4. Test Password Reset (Optional)

​Running Tests

​Backend Tests

​Frontend Linting

​Production Build

​Backend Production Setup

​Frontend Production Build

​Troubleshooting

​CORS Issues

​419 CSRF Token Mismatch

​Database Connection Errors

​Port Already in Use

​Module Not Found Errors

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Installation

Prerequisites

Required Software

Database Options

Verify Installation

Backend Setup (Laravel)

1. Clone the Repository

2. Install Backend Dependencies

3. Environment Configuration

4. Configure Environment Variables

Basic Application Settings

Frontend URL Configuration

Database Configuration

Session and Cache Configuration

Mail Configuration (for Password Reset)

5. Run Database Migrations

6. (Optional) Seed the Database

7. Configure CORS

8. Verify Backend Installation

Frontend Setup (Next.js)

1. Navigate to Frontend Directory

2. Install Frontend Dependencies

3. Configure Environment Variables

4. Verify Frontend Configuration

5. Run Frontend Development Server

Running Both Applications

Option 1: Automated (Recommended)

Option 2: Manual

Testing the Installation

1. Test Backend API

2. Test Frontend

3. Test Authentication Flow

4. Test Password Reset (Optional)

Running Tests

Backend Tests

Frontend Linting

Production Build

Backend Production Setup

Frontend Production Build

Troubleshooting

CORS Issues

419 CSRF Token Mismatch

Database Connection Errors

Port Already in Use

Module Not Found Errors

Next Steps

Additional Resources