Blog Maria Tech

Guía práctica para entorno de desarrollo moderno

Si vienes de trabajar con herramientas como MAMP, probablemente estés acostumbrado a levantar y apagar servicios manualmente cada vez que desarrollas.

Pero cuando empiezas a trabajar con Laravel Valet, el flujo cambia bastante: todo es más rápido, más limpio y mucho más cómodo para proyectos Laravel en macOS.

En este artículo veremos qué es Laravel Valet, cómo instalarlo, cómo configurarlo y cómo solucionar algunos errores comunes que pueden aparecer durante el proceso.

¿Qué es Laravel Valet?

Laravel Valet es un entorno de desarrollo local para macOS que permite ejecutar proyectos PHP y Laravel sin necesidad de configurar servidores virtuales manualmente.

Valet utiliza principalmente:

• Nginx, como servidor web.
• dnsmasq, para resolver dominios locales.
• PHP, instalado normalmente mediante Homebrew.

Con Valet puedes acceder a tus proyectos usando dominios como:

http://proyecto.test

En lugar de depender de rutas como:

http://localhost:8000

Instalación base de Laravel Valet

Antes de instalar Valet es recomendable contar con:

• Homebrew instalado.
• PHP instalado.
• Composer instalado.

Para instalar Valet ejecutamos:

composer global require laravel/valet

Después inicializamos Valet con:

valet install

Este comando configura los servicios necesarios para que Valet funcione correctamente en segundo plano.

Error común: zsh: command not found: valet

Uno de los errores más comunes después de instalar Valet es:

zsh: command not found: valet

Esto normalmente significa que Valet sí fue instalado, pero la ruta global de Composer no está agregada al PATH del sistema.

Para encontrar la ruta global de Composer ejecutamos:

composer global config bin-dir --absolute

El resultado suele ser algo parecido a:

/Users/tu_usuario/.config/composer/vendor/bin

Después agregamos esa ruta al archivo .zshrc:

nano ~/.zshrc

Y añadimos:

export PATH="$HOME/.config/composer/vendor/bin:$PATH"

Finalmente recargamos la configuración:

source ~/.zshrc

Y validamos:

valet --version

Organización de proyectos con “valet park”

Una de las funciones más útiles de Valet es “valet park".

Este comando le indica a Valet que todos los proyectos dentro de una carpeta deben estar disponibles automáticamente como dominios .test.

Por ejemplo:

cd ~/Developments/LaravelProjects
valet park

Si dentro de esa carpeta tenemos:

tu-proyecto-1
tu-proyecto-2
tu-proyecto-3

Entonces podremos acceder a:

http://tu-proyecto-1.test
http://tu-proyecto-2.test
http://tu-proyecto-3.test

Comandos útiles de Valet

Algunos comandos básicos para controlar Valet son:

valet start

Inicia los servicios de Valet.

valet stop

Detiene los servicios de Valet.

valet restart

Reinicia Valet. Es muy útil cuando algo no responde correctamente.

valet paths

Muestra las carpetas que están configuradas con valet park.

valet forget

Elimina el park de la carpeta actual.

Configuración de Node con nvm

Para trabajar con Laravel moderno también necesitamos Node.js, ya que Laravel usa Vite para compilar CSS y JavaScript.

Una buena práctica es manejar Node con nvm, ya que permite instalar y cambiar versiones fácilmente.

Instalamos nvm con Homebrew:

brew install nvm

Creamos la carpeta de configuración:

mkdir ~/.nvm

Después agregamos esto al archivo .zshrc:

export NVM_DIR="$HOME/.nvm"
source $(brew --prefix nvm)/nvm.sh

Recargamos:

source ~/.zshrc

Instalamos una versión de Node:

nvm install 22
nvm use 22

Y la dejamos como versión por defecto:

nvm alias default 22

Si queremos la última versión estable de Node el comando sería:

nvm install --lts

Error común: env: node: No such file or directory

Este error aparece cuando el sistema no encuentra Node:

env: node: No such file or directory

Generalmente ocurre porque nvm no se cargó correctamente en la terminal.

Para solucionarlo podemos ejecutar:

nvm use default

Y validar:

node -v
npm -v

Si el problema continúa, hay que revisar que la configuración de nvm esté correctamente agregada en ~/.zshrc.

Crear un proyecto Laravel

Para crear proyectos Laravel de forma más rápida podemos instalar el instalador oficial:

composer global require laravel/installer

Este comando habilita el comando:

laravel new nombre-proyecto

Por ejemplo:

cd ~/Developments/LaravelProjects
laravel new tu-proyecto-1

Después podemos abrirlo con:

cd tu-proyecto-1
valet open

Y el proyecto estará disponible en:

http://tu-proyecto-1.test

Frontend con Vite

Laravel utiliza Vite para compilar los archivos CSS y JavaScript del proyecto.

Después de crear el proyecto debemos ejecutar:

npm install
npm run dev

El comando npm install instala las dependencias definidas en package.json.

El comando npm run dev levanta Vite en modo desarrollo, permitiendo compilar assets y trabajar con recarga automática (hot reload).

Error común: Failed to resolve import “./bootstrap”

Este error puede aparecer al ejecutar Vite:

Failed to resolve import "./bootstrap" from "resources/js/app.js"

Significa que Laravel está intentando importar este archivo:

resources/js/bootstrap.js

Pero no existe o no fue generado correctamente.

Primero podemos intentar reinstalar dependencias:

rm -rf node_modules package-lock.json
npm install
npm run dev

Si el archivo sigue sin existir, se puede crear manualmente:

touch resources/js/bootstrap.js

Y agregar:

import axios from 'axios';

window.axios = axios;

window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

Error común: Failed to resolve import “axios”

Otro error común es:

Failed to resolve import "axios" from "resources/js/bootstrap.js"

Esto significa que el archivo bootstrap.js intenta importar Axios, pero Axios no está instalado.

La solución es:

npm install axios
npm run dev

Configurar MySQL sin depender de MAMP

Si queremos trabajar sin depender de MAMP, podemos instalar MySQL mediante Homebrew:

brew install mysql

Para iniciar el servicio:

brew services start mysql

Para detenerlo:

brew services stop mysql

Podemos entrar a MySQL con:

mysql -u root

Y crear una base de datos:

CREATE DATABASE tu-proyecto-1 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Agregar contraseña al usuario root de MySQL

Para asignar contraseña al usuario root podemos ejecutar:

ALTER USER 'root'@'localhost' IDENTIFIED BY 'TuPasswordSeguro123!';
FLUSH PRIVILEGES;

Después configuramos el archivo .env de Laravel:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tu-proyecto-1
DB_USERNAME=root
DB_PASSWORD=TuPasswordSeguro123!

Error común: Plugin ‘mysql_native_password’ is not loaded

En versiones recientes de MySQL puede aparecer este error:

ERROR 1524 (HY000): Plugin 'mysql_native_password' is not loaded

Esto ocurre porque MySQL moderno ya no utiliza ese plugin por defecto. Actualmente se usa caching_sha2_password.

La solución es no forzar mysql_native_password y usar:

ALTER USER 'root'@'localhost' IDENTIFIED BY 'TuPasswordSeguro123!';
FLUSH PRIVILEGES;

Flujo recomendado de trabajo

Una vez configurado el entorno, el flujo diario puede ser muy sencillo.

Para iniciar el entorno

brew services start mysql
valet start
cd ~/Developments/LaravelProjects/tu-proyecto-1
npm run dev

Para apagar el entorno

Primero detenemos Vite con:

Ctrl + C

Después detenemos MySQL:

brew services stop mysql

Y opcionalmente Valet:

valet stop

Tip pro: crear alias para iniciar y detener el entorno

Para simplificar el flujo podemos crear alias en ~/.zshrc:

alias up-dev="brew services start mysql && valet start"
alias down-dev="brew services stop mysql && valet stop"

Después recargamos:

source ~/.zshrc

Y ahora podemos iniciar el entorno con:

up-dev

Y apagarlo con:

down-dev

Conclusión

Laravel Valet es una excelente alternativa para desarrollar proyectos Laravel en macOS. Comparado con MAMP, ofrece un flujo más limpio, rápido y cómodo para trabajar con dominios locales, PHP moderno, Composer, Node, Vite y MySQL.

Aunque al inicio pueden aparecer algunos errores relacionados con PATH, Node, dependencias de npm o autenticación de MySQL, la mayoría tienen solución rápida si entendemos cómo está organizado el entorno.

Para desarrolladores que trabajan constantemente con Laravel, una combinación como Laravel Valet + Homebrew + nvm + MySQL puede convertirse en una base de trabajo muy sólida y profesional.