Laravel Breeze: primeros pasos para instalar y usar la autenticación

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 caer directamente en Jetstream o soluciones más complejas, cuando en realidad Laravel Breeze suele ser el mejor punto de partida, aunque es importante mencionar que Laravel Breeze ya no es un paquete oficial para Laravel base (sin Livewire o Inertia) y usualmente te recomendaría que crees un proyecto en Livewire y aproveches el módulo de autenticación que provee o uses Fortify.

En esta guía te muestro los primeros pasos con Laravel Breeze, desde qué es y cuándo usarlo, hasta la instalación real, errores comunes y qué revisar después de tenerlo 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 empezar sin sobrecargar el proyecto.

Laravel Breeze lo definen en la documentación oficial como:

"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."

Y en pocas palabras nos ofrece dos configuraciones a nivel del proyecto:

1. Instalar y configurar Tailwind.css y Alpine.js (que ya no hace falta en versiones modernas de Laravel al estar incluido de base).
2. Instalar y configurar un sencillo esquema de autenticación, registrarse, recuperar la 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

Diferencias entre Breeze, Jetstream y Fortify

Aquí es donde muchos se confunden al empezar:

• Fortify: solo backend, sin vistas. Ideal si quieres construir todo el frontend desde cero.
• Jetstream: muy completo, con equipos, 2FA y más. Perfecto para apps grandes.
• Breeze: equilibrio ideal entre funcionalidad y control.

Breeze es la mejor opción para aprender y para proyectos pequeños o medianos, incluidos MVPs.

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ó”

Importante notar que, no es el objetivo del libro aprender Tailwind.css o Alpine.js, por lo tanto, se da por hecho que el lector tiene ciertos conocimientos sobre estos; se intentará tener el uso a estas tecnologías de manera sencilla, pero, si te pierdes perdido en algún punto, como recomendación general, puedes pausar en capítulo y estudiar un poco estas tecnologías; en mi canal en Youtube encontrarás introducciones a estas tecnologías.

Laravel Breeze es un paquete de autenticación básico que puede ser instalado mediante composer; es un paquete desarrollado exclusivamente para Laravel y que permite agregar de una manera sencilla la funcionalidad de autenticación a una aplicación en Laravel. Breeze utiliza la plantilla Blade, Vue o React para generar cada una de las pantallas visuales y por supuesto, los controladores correspondientes para procesar las peticiones. 

Al instalar Breeze automáticamente la aplicación cuenta con módulos para recuperación de contraseñas, verificación de correo electrónico, login y registrarse, además…

Breeze incluye una página de perfil para actualizar datos básicos del usuario autenticado; y con unos pocos cambios, puedes agregar un sencillo sistema de roles en el módulo de usuario, esto es una configuración que hacemos en el curso y libro completo sobre Laravel.

La página del paquete que vamos a instalar 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, aunque a partir de Laravel 12 ya no aparece como opción directa al crear el proyecto. Esto no es un problema, solo cambia la forma de instalarlo.

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

Aquí es donde más gente se atasca.

Breeze utiliza Vite, lo que implica que necesitas una versión moderna de Node.js. En proyectos reales he visto errores constantes por usar Node antiguo.

Por ejemplo, si ves errores como:

no es un problema de Breeze, sino de Node demasiado antiguo. Versiones como v14.x ya no son suficientes. En mis proyectos suelo trabajar con Node 18+, y con eso no hay problemas.

Entorno local (Laragon, Sail u otros)

Puedes usar Breeze sin problema en:

• Laragon
• XAMPP
• Laravel Sail
• Docker personalizado

Si usas Sail y no tienes Node instalado localmente, también puedes compilar los assets desde el contenedor, como veremos más adelante.

Cómo instalar Laravel Breeze paso a paso

Instalar Breeze con Composer

Para poder instalarlo:

Desde la raíz de tu proyecto Laravel ejecuta:

$ composer require laravel/breeze --dev

Esto añade Breeze como dependencia de desarrollo.

Ejecutar el instalador de Breeze

Luego ejecuta:

$ php artisan breeze:install

Preguntará cual stack queremos emplear; si tienes experiencia, puede seleccionar cualquiera de las tecnologías como Vue o react:

  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

Pero, para iniciar de a poco, se recomienda que emplees la opción de "blade":

$ blade

Puedes habilitar el modo oscuro:

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

Indicando "yes":

$ yes

Entre otras opciones, como las pruebas unitarias, que no serían necesarias:

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

Indicando "no":

$ no

Y esperas hasta que termine el proceso:

INFO  Installing and building Node dependencies.

Compilar assets y ejecutar el proyecto

Después de instalar Breeze, necesitas compilar los assets.

Ejecuta:

$ npm install
$ npm run dev

Este comando:

• Compila Tailwind y JS
• Genera los archivos finales

Usar npm con Laravel Sail

Si usas Sail y no tienes Node instalado localmente:

./vendor/bin/sail npm run dev

Esto significa que los cambios que hagas en el código se reflejan automáticamente en el navegador.

Manejo de errores con Node

Si ves algún error como el siguiente:

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

error when starting dev server:

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 muy antigua; puedes conocer tu versión de Node con:

$ node -v

Si vez una versión similar o inferior a esta:

v14.16.1

En el libro, estamos usando:

$ node -v
v18.8.0

Debes de actualizar tu versión; luego puedes ejecutar:

$ npm run dev

En el caso de estar empleando Laravel Sail y no tener instalado Node en tu equipo:

$ ./vendor/bin/sail npm run dev

Finalmente, veremos que es sobrescrito nuestro esquema de rutas en:

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

Configurar tus rutas

Y recuerda colocar nuevamente las rutas sobrescritas:

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

Si revisamos los archivos generados en la carpeta de resources, veremos:

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 nuestro proyecto con las importaciones correspondientes para tal fin.

Finalmente, el comando de npm run dev, genera los archivos de salida y levanta un proceso para el Hot Reload Replacement que permite sincronizar los cambios que hagamos en el código fuente con lo que estamos viendo en el navegador.

Qué stack elegir al empezar (Blade vs Vue vs React)

Aunque Breeze permite Blade, Vue, React, Livewire e incluso API-only, para primeros pasos siempre recomiendo Blade.

Blade te permite:

• Entender mejor la estructura de Laravel
• Evitar complejidad innecesaria
• Personalizar vistas sin aprender un framework JS completo

Si ya tienes experiencia, puedes elegir Vue o React sin problema, pero para aprender, Blade es la opción más sensata.

Sistema de autenticación

Aparte de la configuración de Tailwind y Alpine, Laravel Breeze configura un sencillo esquema de autenticación que vamos a emplear a continuación.

Si vamos a:

http://larafirststeps.test/login

Veremos la siguiente pantalla:

Una página de login, pero, necesitamos crear un usuario:

http://larafirststeps.test/register

Creamos alguno:

Y si vamos a la base de datos:

Por defecto ya iniciamos login; y como puedes ver, ya tenemos listo un bonito layout para nuestra aplicación; en el proyecto:

Verás unos archivos de vistas que ya nos generó Laravel Breeze:

Te recomiendo que le des una buena revisada, y verás todas las opciones que tenemos; registrar, login, recuperar contraseña y cerrar sesión:

Opciones del instalador de Breeze explicadas

Durante la instalación verás varias preguntas.

• Soporte para modo oscuro
  • Puedes activar soporte para dark mode. No es obligatorio, pero viene bien y no añade complejidad real.
• Pruebas con Pest o PHPUnit
  • Si estás empezando, no necesitas pruebas desde el primer momento. En muchos proyectos iniciales prefiero decir “no” y añadir tests más adelante cuando el flujo esté claro.
• Qué genera realmente cada opción
• Breeze genera:
  • Rutas
  • Controladores
  • Vistas
  • Componentes Blade
  • Configuración frontend
• Nada de esto es “mágico”. Todo queda en tu proyecto para que lo modifiques.

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

• Error “Cannot find module 'node:path'”
  • Este error indica Node antiguo. Comprueba tu versión:

  • node -v

• Si ves algo como v14.x, actualiza. En proyectos reales trabajo con versiones como v18.x sin problemas.
• Versiones de Node incompatibles
  • Laravel moderno + Vite requieren Node moderno. Actualizar Node soluciona el 90 % de los errores iniciales.
• Problemas con Vite en entornos Windows
  • En Windows, rutas mal configuradas o permisos pueden causar errores. Normalmente se solucionan:
    • Actualizando Node
    • Eliminando node_modules
    • Ejecutando de nuevo npm install