Breeze: Guía de instalación y usar la autenticación en Laravel 11, 12 y 13

Cuando empiezas un proyecto en Laravel y necesitas autenticación, una de las primeras decisiones importantes es qué solución usar. Durante años he visto a muchos desarrolladores saltar directamente a Jetstream o a soluciones más complejas, cuando en realidad Laravel Breeze suele ser el mejor punto de partida.

Dicho esto, es importante aclarar algo desde el principio: Laravel Breeze ya no es el paquete de autenticación recomendado para proyectos nuevos en Laravel 13 sin Livewire o Inertia. Si estás arrancando un proyecto moderno, te recomendaría crear el proyecto con Livewire y aprovechar su módulo de autenticación integrado, o bien usar Fortify directamente. Aun así, entender Breeze sigue siendo muy valioso, tanto para mantener proyectos existentes como para comprender cómo funciona la autenticación en Laravel desde sus cimientos.

En esta guía te muestro los primeros pasos con Laravel Breeze: qué es, cuándo tiene sentido usarlo, cómo instalarlo en Laravel 11, 12 y 13, los errores más comunes y qué revisar una vez que lo tienes funcionando. No es solo teoría; es exactamente el flujo que uso y enseño en mis proyectos, cursos y libros.

Qué es Laravel Breeze y cuándo usarlo

Laravel Breeze es el starter kit oficial de Laravel para implementar autenticación básica de forma rápida y limpia. Incluye todo lo necesario para arrancar sin sobrecargar el proyecto con funcionalidades que quizás no necesitas.

La documentación oficial de Laravel lo define así:

"Laravel Breeze es una implementación mínima y simple de todas las funciones de autenticación de Laravel, incluido el inicio de sesión, el registro, el restablecimiento de contraseña, la verificación de correo electrónico y la confirmación de contraseña. La capa de vista predeterminada de Laravel Breeze se compone de vistas Blade simples diseñadas con Tailwind CSS."

En términos prácticos, al instalar Breeze en tu proyecto obtienes dos cosas fundamentales:

1. La configuración de Tailwind CSS y Alpine.js en el proyecto (aunque en versiones modernas de Laravel esto ya viene incluido de base).
2. Un esquema de autenticación completo: registro, inicio de sesión, recuperación de contraseña y middleware para el control de acceso.

Qué incluye Laravel Breeze por defecto

Al instalar Breeze obtienes, entre otras cosas:

• Registro de usuarios
• Inicio y cierre de sesión
• Recuperación de contraseña
• Verificación de correo electrónico
• Página de perfil del usuario
• Middleware de autenticación (auth, verified)
• Vistas listas para usar con Tailwind CSS

Todo este código queda publicado directamente en tu proyecto, lo que significa que puedes leerlo, modificarlo y adaptarlo sin depender de ninguna capa oculta. Eso es precisamente lo que lo hace tan valioso para aprender.

Diferencias entre Breeze, Jetstream y Fortify

Aquí es donde muchos se confunden al empezar. Las tres opciones resuelven el mismo problema (la autenticación), pero desde ángulos muy distintos:

• Fortify: solo backend, sin vistas. Ideal si quieres construir todo el frontend desde cero o integrarlo con Vue, React u otro framework. No genera ningún archivo de vista.
• Jetstream: muy completo, con equipos, autenticación de dos factores (2FA), gestión de sesiones y más. Perfecto para aplicaciones grandes que necesitan todo esto desde el día uno.
• Breeze: el equilibrio ideal entre funcionalidad y control. Genera vistas reales que puedes editar, sin añadir complejidad que no necesitas.

Breeze es la mejor opción para aprender y para proyectos pequeños o medianos, incluidos MVPs. Si no sabes cuál elegir, empieza por Breeze.

Para qué tipo de proyectos recomiendo Laravel Breeze

Recomiendo Breeze cuando:

• Estás dando tus primeros pasos con Laravel
• Quieres autenticación rápida sin complejidad
• Necesitas una base clara para personalizar después
• Prefieres entender qué pasa “bajo el capó” antes de confiar en soluciones más abstractas

Una aclaración importante: el objetivo de este capítulo no es aprender Tailwind CSS ni Alpine.js en profundidad. Se asume que el lector tiene ciertos conocimientos previos sobre estas tecnologías. Intentaremos usarlas de forma sencilla, pero si en algún punto te sientes perdido, la recomendación es pausar aquí y estudiar un poco antes de continuar. En mi canal de YouTube encontrarás introducciones a ambas herramientas.

La página oficial del paquete está en:

https://laravel.com/docs/master/starter-kits

Requisitos previos antes de instalar Laravel Breeze

Antes de instalar Breeze conviene revisar algunos puntos básicos que suelen generar problemas si se pasan por alto.

Versión de Laravel compatible (Laravel 11, 12 y 13)

Laravel Breeze funciona perfectamente en Laravel 11 y Laravel 12. A partir de Laravel 13, Breeze ya no aparece como opción directa al crear el proyecto con laravel new, pero esto no es un impedimento: simplemente cambia la forma de instalarlo, que veremos en detalle a continuación.

Node.js, NPM y Vite: lo mínimo necesario

Aquí es donde más gente se atasca. Breeze utiliza Vite para compilar los assets del frontend, lo que implica que necesitas una versión moderna de Node.js. En proyectos reales he visto errores constantes provocados por versiones antiguas de Node.

Por ejemplo, si ves errores como Cannot find module 'node:path', no es un problema de Breeze en sí, sino de que tu versión de Node es demasiado antigua. Las versiones v14.x ya no son suficientes. En mis proyectos trabajo habitualmente con Node 18+, y con eso no hay problemas.

Entorno local (Laragon, Sail, Herd u otros)

Puedes usar Breeze sin problema en cualquiera de estos entornos:

• Laragon
• XAMPP
• Laravel Sail
• Laravel Herd
• Docker personalizado

Si usas Sail y no tienes Node instalado localmente, también puedes compilar los assets desde el contenedor usando ./vendor/bin/sail npm run dev, como veremos más adelante.

Cómo instalar Laravel Breeze paso a paso

Instalar Breeze con Composer

Desde la raíz de tu proyecto Laravel, ejecuta el siguiente comando para añadir Breeze como dependencia de desarrollo:

$ composer require laravel/breeze --dev

Al usar el flag --dev, Breeze se instala únicamente como dependencia de desarrollo. Esto tiene sentido porque el paquete publica su código en tu proyecto y luego ya no es necesario en producción.

Ejecutar el instalador de Breeze

Una vez instalado el paquete, ejecuta el instalador de Artisan:

$ php artisan breeze:install

El instalador te preguntará qué stack quieres emplear. Si tienes experiencia con otros frameworks, puedes elegir vue o react, pero para empezar de a poco, la opción recomendada es blade:

 Which Breeze stack would you like to install?
  Blade with Alpine ........................................ blade
  Livewire (Volt Class API) with Alpine ................... livewire
  Livewire (Volt Functional API) with Alpine .............. livewire-functional
  React with Inertia ...................................... react
  Vue with Inertia ........................................ vue
  API only ................................................ api

Selecciona blade para continuar. A continuación, el instalador te ofrecerá activar el soporte para modo oscuro:

Would you like to install dark mode support?
  (yes/no) [no]

Responde yes si lo deseas. Es una opción que no añade complejidad real y viene bien para proyectos que necesitan soporte de tema oscuro desde el principio.

Luego te preguntará si prefieres usar Pest en lugar de PHPUnit para las pruebas:

Would you prefer Pest tests instead of PHPUnit?
  (yes/no) [no]

Si estás empezando, responde no. Puedes añadir tests más adelante cuando el flujo del proyecto esté claro. Finalmente, espera a que el proceso termine de instalar y compilar las dependencias:

INFO  Installing and building Node dependencies.

Compilar assets y ejecutar el proyecto

Después de instalar Breeze, necesitas compilar los assets del frontend. Ejecuta:

$ npm install
$ npm run dev

Estos comandos hacen lo siguiente:

• Instalan las dependencias de Node.js declaradas en package.json
• Compilan Tailwind CSS y el JavaScript de Alpine.js
• Levantan un proceso de Hot Module Replacement (HMR) que sincroniza automáticamente los cambios del código fuente con el navegador

Usar npm con Laravel Sail

Si usas Sail y no tienes Node instalado localmente, puedes compilar los assets directamente desde el contenedor:

./vendor/bin/sail npm run dev

Manejo de errores con Node

Si ves un error como el siguiente al ejecutar npm run dev:

failed to load config from C:\laragon\www\testlara11\vite.config.js

Error: Cannot find module 'node:path'
Require stack:
- C:\laragon\www\testlara11\node_modules\vite\dist\node-cjs\publicUtils.cjs
- C:\laragon\www\testlara11\node_modules\vite\index.cjs
- C:\laragon\www\testlara11\vite.config.js

Significa que tienes una versión de Node demasiado antigua. Verifica tu versión actual con:

$ node -v

Si el resultado es similar o inferior a:

v14.16.1

Necesitas actualizar. En este proyecto trabajamos con:

v18.8.0

Una vez actualizado Node, vuelve a ejecutar:

$ npm run dev

Y si estás usando Laravel Sail sin Node local:

$ ./vendor/bin/sail npm run dev

Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware(['auth', 'verified'])->name('dashboard');

Configurar tus rutas después de instalar Breeze

Al instalar Breeze, el archivo de rutas es sobrescrito y verás algo como esto en routes/web.php:

Route::get('/dashboard', function () {
    return view('dashboard');
})->middleware(['auth', 'verified'])->name('dashboard');

Esto es completamente normal. Recuerda volver a añadir tus rutas personalizadas. Por ejemplo, si ya tenías controladores de recursos:

use App\Http\Controllers\Dashboard\CategoryController;
use App\Http\Controllers\Dashboard\PostController;

Route::group(['prefix' => 'dashboard'], function () {
    Route::resources([
        'post' => PostController::class,
        'category' => CategoryController::class,
    ]);
});

Recursos CSS y JavaScript generados por Breeze

Si revisas los archivos generados en la carpeta resources, encontrarás lo siguiente:

resources/css/app.css

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

resources/js/app.js

import './bootstrap';

import Alpine from 'alpinejs';

window.Alpine = Alpine;

Alpine.start();

Breeze configuró Tailwind CSS y Alpine.js en tu proyecto con las importaciones correspondientes. El comando npm run dev genera los archivos de salida y levanta el proceso de Hot Reload para que los cambios se reflejen automáticamente en el navegador.

Qué stack elegir al empezar: Blade vs Vue vs React

Aunque Breeze soporta blade, vue, react, livewire e incluso api, para primeros pasos siempre recomiendo blade.

Blade te permite:

• Entender mejor la estructura interna de Laravel
• Evitar complejidad innecesaria al inicio
• Personalizar vistas sin tener que aprender un framework JavaScript completo al mismo tiempo

Si ya tienes experiencia con Vue o React, puedes elegirlos sin problema. Pero si estás aprendiendo, blade es la opción más sensata para no mezclar demasiadas tecnologías nuevas a la vez.

Sistema de autenticación

Aparte de configurar Tailwind CSS y Alpine.js, Laravel Breeze instala un esquema de autenticación completo que vamos a explorar a continuación.

Si navegas a:

http://larafirststeps.test/login

Verás la pantalla de inicio de sesión:

Antes de hacer login, necesitas crear un usuario. Para eso, accede a la ruta de registro:

http://larafirststeps.test/register

Completa el formulario y crea tu primer usuario:

Y si vamos a la base de datos:

Una vez registrado, por defecto el usuario queda autenticado automáticamente y es redirigido al /dashboard, donde verás el layout que Breeze genera para la aplicación:

Breeze también genera una serie de vistas en la carpeta resources/views que puedes explorar y modificar libremente:

Te recomiendo que les des una buena revisada. Encontrarás las vistas para registrarse, hacer login, recuperar la contraseña y cerrar sesión, todo listo para personalizar:

Opciones del instalador de Breeze explicadas

Durante la instalación de Breeze verás varias preguntas. Aquí te explico qué significa cada una:

• Soporte para modo oscuro: Puedes activar soporte para dark mode desde el instalador. No es obligatorio, pero tampoco añade complejidad real. Si tu proyecto puede necesitarlo, actívalo desde el principio; es más fácil hacerlo ahora que añadirlo después.
• Pruebas con Pest o PHPUnit: Si estás empezando, no necesitas configurar pruebas desde el primer momento. En muchos proyectos iniciales prefiero responder no y añadir los tests más adelante, cuando el flujo del proyecto esté bien definido. Tanto Pest como PHPUnit son buenas opciones; en proyectos modernos de Laravel suelo preferir Pest por su sintaxis más expresiva.
• Qué genera realmente cada opción: Independientemente del stack que elijas, Breeze publica en tu proyecto:
  • Rutas de autenticación en routes/auth.php
  • Controladores en app/Http/Controllers/Auth/
  • Vistas en resources/views/auth/
  • Componentes Blade en resources/views/components/
  • Configuración del frontend (vite.config.js, tailwind.config.js)
• Nada de esto es “mágico”. Todo el código generado queda en tu proyecto para que lo leas, entiendas y modifiques sin restricciones.

Errores comunes al instalar Laravel Breeze (y cómo solucionarlos)

• Error Cannot find module 'node:path': Este error indica que tu versión de Node es demasiado antigua. Verifica tu versión con:

  node -v

  Si ves algo como v14.x, necesitas actualizar. En proyectos reales trabajo con v18.x o superior sin ningún problema.

• Versiones de Node incompatibles: Laravel moderno junto con Vite requieren versiones actualizadas de Node.js. Actualizar Node soluciona el 90% de los errores iniciales relacionados con el frontend.
• Problemas con Vite en entornos Windows: En Windows, rutas mal configuradas o problemas de permisos pueden causar errores al compilar. La mayoría de estos problemas se resuelven con los siguientes pasos:
  • Actualizar Node.js a una versión LTS moderna (v18+ o v20+)
  • Eliminar la carpeta node_modules
  • Ejecutar de nuevo npm install y luego npm run dev
• Rutas sobrescritas en routes/web.php: Breeze modifica tu archivo de rutas al instalarse. Revisa el archivo después de la instalación y restaura las rutas personalizadas que tenías antes.