Laravel Breeze API + Next.js TypeScript

Un template moderno y profesional que combina un backend robusto con Laravel 12 y un frontend elegante con Next.js 16, TypeScript y Tailwind CSS. Este proyecto es una extensión mejorada de Laravel Breeze Next TypeScript con funcionalidades adicionales en el backend.

🎯 Descripción

Este template proporciona una solución fullstack completa y lista para producción, combinando:

• Backend: API RESTful moderna con Laravel 12, autenticación mediante Sanctum y una estructura escalable
• Frontend: Aplicación React moderna con TypeScript, Tailwind CSS y componentes respetuosos con la accesibilidad

Ideal para desarrollar aplicaciones web SPA (Single Page Application) con seguridad robusta y experiencia de usuario moderna.

🚀 Características Principales

Backend (Laravel 12)

• ✅ Laravel 12 - Framework PHP moderno y maduro
• ✅ Laravel Sanctum - Autenticación API segura con tokens
• ✅ CORS Configurado - Comunicación segura entre frontend y backend
• ✅ Breeze Starter Kit - Estructura de autenticación preconfigurada
• ✅ Pest Testing - Framework moderno de testing para PHP
• ✅ Base de datos - Migraciones y seeders listos
• ✅ Queue Support - Sistema de colas para tareas asincrónicas
• ✅ PHP 8.2+ - Últimas características del lenguaje

Frontend (Next.js 16)

• ✅ Next.js 16 - Framework React con soporte SSR y optimizaciones
• ✅ TypeScript - Tipado estático para mejor experiencia de desarrollo
• ✅ Tailwind CSS - Framework CSS moderno y utilitario
• ✅ React 19 - Última versión de React
• ✅ Formik + Yup - Manejo de formularios y validaciones
• ✅ Axios - Cliente HTTP para consumir la API
• ✅ SWR - Fetching de datos con caching y revalidación
• ✅ ESLint - Análisis de código estático
• ✅ Headless UI - Componentes accesibles sin estilos

📋 Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

• PHP 8.2 o superior - Verificar con php --version
• Composer - Gestor de dependencias de PHP
• Node.js 18+ - Runtime de JavaScript
• npm o pnpm - Gestor de paquetes (recomendado pnpm)
• Git - Control de versiones
• MySQL o PostgreSQL - Base de datos (opcional, SQLite para desarrollo)

🔧 Instalación Rápida

1️⃣ Clonar el Repositorio

git clone <tu-repositorio>
cd LaravelBreezeApi_Nextjs

2️⃣ Configuración del Backend

cd Backend

# Instalar dependencias
composer install

# Copiar archivo de configuración
cp .env.example .env

# Generar clave de aplicación
php artisan key:generate

# Ejecutar migraciones
php artisan migrate

# (Opcional) Ejecutar seeders
php artisan db:seed

3️⃣ Configuración del Frontend

cd ../Frontend

# Instalar dependencias
pnpm install
# o si usas npm
npm install

🏃 Ejecución

Opción 1: Ejecutar Todo Junto (Recomendado)

Desde la raíz del proyecto Backend:

composer run dev

Esto ejecutará en paralelo:

• Servidor Laravel (php artisan serve)
• Cola de trabajos (php artisan queue:listen)
• Servidor de desarrollo de Next.js (npm run dev)

Opción 2: Ejecutar Manualmente

Terminal 1 - Backend:

cd Backend
php artisan serve

Terminal 2 - Frontend:

cd Frontend
pnpm dev
# o npm run dev

Acceso a la Aplicación

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/api

📁 Estructura del Proyecto

LaravelBreezeApi_Nextjs/
├── Backend/                          # API Laravel 12
│   ├── app/
│   │   ├── Http/
│   │   │   ├── Controllers/         # Controladores API
│   │   │   ├── Middleware/          # Middlewares personalizados
│   │   │   └── Requests/            # Form Requests (validación)
│   │   └── Models/                  # Modelos Eloquent
│   ├── config/                       # Archivos de configuración
│   ├── database/
│   │   ├── migrations/              # Migraciones BD
│   │   ├── seeders/                 # Seeders de datos
│   │   └── factories/               # Factories para testing
│   ├── routes/
│   │   ├── api.php                  # Rutas API
│   │   └── auth.php                 # Rutas autenticación
│   ├── tests/                        # Tests con Pest
│   └── storage/                      # Archivos y logs
│
├── Frontend/                         # App Next.js 14
│   ├── src/
│   │   ├── app/                     # App Router de Next.js
│   │   ├── components/              # Componentes React
│   │   ├── hooks/                   # Custom React Hooks
│   │   ├── lib/                     # Utilidades y helpers
│   │   └── types/                   # Tipos TypeScript
│   ├── public/                       # Assets estáticos
│   └── tailwind.config.ts           # Configuración Tailwind
│
└── README.md                         # Este archivo

🔐 Autenticación

El proyecto utiliza Laravel Sanctum para autenticación API:

1. El usuario se registra/inicia sesión en el frontend
2. El backend valida las credenciales y genera un token
3. El token se almacena en el frontend (localStorage/cookies)
4. Todas las peticiones incluyen el token en el header Authorization: Bearer <token>

Endpoints Principales de Autenticación

POST   /api/auth/register          # Registrar nuevo usuario
POST   /api/auth/login              # Iniciar sesión
POST   /api/auth/logout             # Cerrar sesión
GET    /api/user                    # Obtener datos del usuario actual
POST   /api/auth/forgot-password    # Solicitar reset de contraseña

🔌 Exportación de Postman

Este proyecto incluye el paquete Laravel API to Postman que permite generar automáticamente una colección de Postman basada en tus rutas API.

Instalación

El paquete ya está incluido en las dependencias. Si necesitas reinstalarlo:

composer require andreaselia/laravel-api-to-postman

Y publica el archivo de configuración:

php artisan vendor:publish --provider="AndreasElia\PostmanGenerator\PostmanGeneratorServiceProvider"

Uso

Para generar la colección de Postman, ejecuta:

php artisan export:postman

Esto generará un archivo JSON en storage/app/ que puedes importar directamente en Postman.

Con Autenticación Bearer Token

php artisan export:postman --bearer="1|XXNKXXqJjfzG8XXSvXX1Q4pxxnkXmp8tT8TXXKXX"

Con Autenticación Basic Auth

php artisan export:postman --basic="username:password123"

El archivo generado incluirá automáticamente:

• ✅ Todas las rutas API
• ✅ Métodos HTTP correctos (GET, POST, PUT, DELETE)
• ✅ Parámetros y validaciones de FormRequest
• ✅ Headers de autenticación (si se especifican)
• ✅ Agrupación por carpetas para mejor organización

Configuración

El archivo de configuración se encuentra en Backend/config/api-postman.php donde puedes personalizar:

• Nombre y descripción de la colección
• Rutas a excluir
• Formato de salida
• Y más opciones

Para más detalles, consulta la documentación oficial del paquete.

📚 Documentación y Recursos

Backend (Laravel)

• Documentación Oficial de Laravel
• Laravel Sanctum
• Pest Testing

Frontend (Next.js)

• Documentación Oficial de Next.js
• Tailwind CSS
• TypeScript en React

🧪 Testing

Backend

cd Backend

# Ejecutar todos los tests
composer test

# Ejecutar tests específicos
php artisan test Feature/Auth

Frontend

cd Frontend

# Ejecutar linter
pnpm lint

🚀 Despliegue

Requisitos para Producción

• Hosting con soporte para PHP 8.2+
• Node.js en el servidor (para Next.js)
• HTTPS obligatorio
• Base de datos de producción (MySQL/PostgreSQL)
• Variable de entorno APP_ENV=production

Build para Producción

Backend:

cd Backend
composer install --no-dev --optimize-autoloader
composer dump-autoload

Frontend:

cd Frontend
pnpm build
pnpm start

🤝 Contribuir

Las contribuciones son bienvenidas. Para cambios principales:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE.md para más detalles.

🙏 Créditos

• Frontend Base: Laravel Breeze Next TypeScript por @Byandev
• Backend: Laravel 12 y Laravel Breeze oficial
• Comunidad: Laravel y Next.js communities

📞 Soporte

Si encuentras problemas:

1. Revisa la sección de Issues en GitHub
2. Consulta la documentación oficial de Laravel y Next.js
3. Verifica que todas las dependencias estén correctamente instaladas
4. Asegúrate de que las variables de entorno estén configuradas

---

Hecho con ❤️ usando Laravel 12 y Next.js 16