Guía para Configurar de Forma Independiente la Versión de Node.js por Proyecto con ServBay (macOS)

ServBay es un poderoso entorno de desarrollo web local diseñado específicamente para desarrolladores, que ofrece una solución integral integrando múltiples lenguajes de programación, bases de datos y servidores web, incluido Node.js. Una de las ventajas más destacadas de ServBay es su soporte nativo para múltiples versiones de Node.js y su gestión flexible. Mediante un sencillo archivo de configuración, puedes especificar fácilmente la versión de Node.js necesaria para cada proyecto, sin depender de gestores de versiones externos como NVM o fnm, ni recurrir a contenedores Docker, lo que simplifica tu flujo de trabajo y evita la contaminación del entorno global y conflictos de versiones.

En este artículo aprenderás cómo aprovechar el archivo .servbay.config de ServBay para controlar la versión de Node.js a nivel de proyecto.

¿Por qué usar .servbay.config de ServBay para gestionar versiones de Node.js?

Los métodos tradicionales de gestión de versiones de Node.js, como NVM o la instalación manual, pueden presentar ciertos inconvenientes:

• Contaminación y conflictos globales: Instalar versiones globalmente o cambiar la versión global con un gestor puede causar conflictos de dependencias entre proyectos distintos.
• Tiempo y complejidad de instalación: Instalar nuevas versiones o cambiar de arquitectura (como x86_64 y arm64) puede requerir la recompilación de módulos, siendo un proceso lento y complejo.
• Sobrecarga de Docker: Usar un contenedor Docker completo solo para gestionar una versión específica de Node.js puede resultar excesivo para necesidades simples.

ServBay proporciona una solución más elegante preinstalando varias versiones populares de Node.js (actualmente soporta todas las versiones mayores y menores desde la v12 hasta la v23, que puedes revisar y gestionar en la sección “Paquetes” de la app ServBay), y junto con el archivo .servbay.config, ofrece:

• Cambio instantáneo: Las versiones ya están preinstaladas; cambiar es casi instantáneo.
• Aislamiento por proyecto: La configuración solo afecta al directorio del proyecto, logrando una auténtica separación de versiones por proyecto.
• Sin contaminación global: No modifica el entorno global del sistema, manteniéndolo limpio.
• Integración con ServBay: Integración fluida con el entorno de desarrollo de ServBay y otros paquetes gestionados (como PHP, bases de datos, servidores web, etc.).

Requisitos Previos

Antes de comenzar, asegúrate de que:

1. Tienes ServBay instalado y funcionando en tu macOS.
2. Has habilitado en el listado de “Paquetes” de la app ServBay la versión de Node.js requerida por tu proyecto.
3. Cuentas con el directorio de tu proyecto donde necesitas especificar una versión concreta de Node.js.

Principio de funcionamiento

ServBay, operando dentro de su terminal integrada, monitoriza el directorio actual. Cuando usas el comando cd para navegar, ServBay busca hacia arriba desde ese directorio archivos llamados .servbay.config, tanto en el directorio actual como en sus padres. Una vez que encuentra dicho archivo (dando prioridad al más cercano), lee sus opciones y ajusta dinámicamente las variables de entorno de la sesión de terminal activa, por ejemplo, modificando la variable PATH para apuntar a la ubicación de la versión de Node.js indicada en el .servbay.config.

Este mecanismo asegura que cada sesión de terminal en un directorio de proyecto pueda cargar y utilizar automáticamente la versión de Node.js especificada, sin necesidad de cambiarla manualmente.

Pasos de configuración

Configurar una versión de Node.js independiente por proyecto es muy sencillo, solo sigue estos dos pasos:

Paso 1: Crear y editar el archivo .servbay.config

En el directorio raíz de tu proyecto (generalmente donde está el archivo package.json), crea un archivo nuevo llamado .servbay.config.

Ábrelo con tu editor de texto favorito y agrega lo siguiente:

# Especifica la versión principal de Node.js a usar en el proyecto
# ServBay seleccionará automáticamente la última versión instalada de esta rama
NODE_VERSION=20

# Opcional: Configura el mirror de npm o pnpm para acelerar la instalación de dependencias
# Si estás en China continental, se recomienda utilizar mirrors nacionales
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Opcional: Especifica el directorio de caché de npm o pnpm
# Se recomienda ubicarlo en el directorio temporal de ServBay para evitar ocupar espacio o contaminar el directorio del usuario
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Descripción de cada opción:

• NODE_VERSION: Obligatorio. Indica la versión principal de Node.js necesaria para el proyecto. Por ejemplo, si pones 20, se usará la última versión instalada de la rama 20.x en ServBay. Asegúrate de que la versión esté instalada.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Opcional. Configura la URL del registro de paquetes para Yarn o npm. Es especialmente útil para acelerar la instalación de dependencias en conexiones lentas o con restricciones.
• NPM_CONFIG_CACHE: Opcional. Define el directorio de caché de npm o pnpm. Si lo ubicas en el directorio temporal de ServBay (/Applications/ServBay/tmp/npm/cache), tendrás mayor control sobre los archivos de caché y evitarás que se dispersen por todo el sistema.

Guarda y cierra el archivo .servbay.config.

Paso 2: Verificar la versión seleccionada en la terminal de ServBay

1. Abre la interfaz principal de ServBay.

2. Haz clic en el botón “Terminal” para lanzar la terminal integrada.

3. Usa el comando cd para acceder al directorio de tu proyecto:

   cd /Applications/ServBay/www/your-project-name

   (Sustituye /Applications/ServBay/www/your-project-name por la ruta real de tu proyecto)

4. Ejecuta el comando node -v para verificar la versión de Node.js activa:

   node -v

   El resultado debería mostrar la versión especificada en tu archivo .servbay.config (por ejemplo, v20.x.x).

5. Puedes también ejecutar npm -v (o pnpm -v, yarn -v) para confirmar que el gestor de paquetes también está correctamente asociado a la versión actual de Node.js.

Ahora, cualquier comando Node.js o npm/pnpm/yarn que ejecutes dentro de este directorio usará la versión y configuración especificada en tu .servbay.config.

Ejemplo de uso

Veamos un ejemplo sencillo de cómo .servbay.config permite el cambio automático de versión de Node.js entre diferentes proyectos.

Supón que tienes dos proyectos: project-a necesita Node.js v18 y project-b requiere Node.js v20.

1. Crear directorios de proyecto y archivos de configuración:

   # Crea los directorios de proyectos de ejemplo en la carpeta www de ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Crea .servbay.config para project-a con Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Crea .servbay.config para project-b con Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Verificar el cambio en la terminal de ServBay:

   Abre la terminal de ServBay y ejecuta lo siguiente:

   # Entra al directorio de project-a
   cd /Applications/ServBay/www/project-a
   # Verifica la versión de Node.js
   node -v
   # Salida esperada: v18.x.x
   
   # Ve a project-b
   cd ../project-b
   # Verifica la versión de Node.js
   node -v
   # Salida esperada: v20.x.x
   
   # Vuelve a project-a
   cd ../project-a
   # Verifica la versión de Node.js
   node -v
   # Salida esperada: v18.x.x

Como puedes ver, ServBay ajusta automáticamente la variable NODE_VERSION de acuerdo al directorio actual, permitiéndote cambiar entre versiones de Node.js sin esfuerzo según el archivo .servbay.config de cada proyecto.

La imagen siguiente ilustra cómo al cambiar de directorio de proyecto, la versión de Node.js varía automáticamente en función del .servbay.config (la imagen es ilustrativa, la interfaz real puede variar):

Consideraciones

• El archivo .servbay.config debe estar ubicado en el directorio del proyecto o en alguno de sus directorios padres. ServBay buscará hacia arriba y usará el primer archivo .servbay.config que encuentre (el más cercano al directorio actual).
• Asegúrate de trabajar en la terminal integrada de ServBay o en una terminal externa que ya tenga configuradas las variables de entorno de ServBay.
• La versión indicada en NODE_VERSION debe estar instalada y habilitada en ServBay. Si especificas una versión que no existe, ServBay puede volver a la versión por defecto o no encontrar el comando Node.js.
• Las configuraciones en .servbay.config solo afectan la sesión de terminal actual y sus procesos hijos; no afectan el sistema global ni otros procesos fuera del entorno de ServBay.

Preguntas Frecuentes (FAQ)

P: ¿Qué ocurre si mi directorio de proyecto no tiene archivo .servbay.config?

R: Si ServBay no encuentra ningún archivo .servbay.config en el directorio actual ni en sus padres, usará la configuración global de ServBay o la versión por defecto de Node.js (habitualmente la marcada como “defecto” en ServBay).

P: ¿Cómo sé qué versiones de Node.js soporta ServBay?

R: Abre la app ServBay y navega a la sección “Paquetes” en el menú lateral izquierdo. Allí verás una lista de todos los paquetes disponibles e instalados, incluyendo las distintas versiones de Node.js. Puedes activar o desactivar versiones seleccionándolas.

P: ¿La configuración de .servbay.config afecta todo mi sistema?

R: No. La configuración de .servbay.config es temporal y limitada a la sesión de terminal de ServBay o procesos que usan sus variables de entorno. No modifica variables globales de tu sistema ni afecta programas externos a ServBay. Este es el mecanismo clave para garantizar el aislamiento entre proyectos.

P: ¿Puedo configurar otros parámetros de ServBay en .servbay.config además de NODE_VERSION?

R: Sí, el archivo .servbay.config es un mecanismo genérico para definir variables de entorno a nivel de proyecto en ServBay. Además de las opciones relacionadas con Node.js, puedes establecer otros valores de entorno que serán interpretados por los comandos ejecutados desde ese directorio. El listado de opciones puede variar según la versión de ServBay, pero la definición de variables de entorno es el núcleo de esta funcionalidad.

Conclusión

Aprovechando el archivo .servbay.config de ServBay, puedes asignar y gestionar de forma eficiente e independiente la versión de Node.js para cada uno de tus proyectos locales. Este método es más ligero y conveniente que los gestores de versiones tradicionales o las soluciones basadas en contenedores, y se integra perfectamente en el entorno de desarrollo de ServBay, ayudando a crear un flujo de trabajo más estable y colaborativo. ¡Empieza a usar .servbay.config en tus proyectos y disfruta de las ventajas que ServBay tiene para ofrecerte!