Crear y ejecutar proyectos Koa.js con ServBay
ServBay es un entorno de desarrollo web local compatible con macOS y Windows, que integra una amplia selección de herramientas esenciales para desarrolladores, incluyendo el runtime de Node.js y múltiples sistemas de bases de datos. En este artículo te explicamos cómo aprovechar ServBay para crear, ejecutar y administrar tus proyectos Koa.js de forma práctica y eficiente.
¿Qué es Koa.js?
Koa.js es un framework web de próxima generación basado en Node.js y desarrollado por el equipo de Express.js. Destaca por su simplicidad, expresividad y conjunto de características potentes, siendo una opción ideal para construir aplicaciones web y APIs. Koa.js aprovecha las funcionalidades modernas de JavaScript, en especial la sintaxis async/await
, lo que facilita la gestión de operaciones asíncronas y la escritura de middleware, haciendo que el código sea más claro y fácil de mantener.
Características principales de Koa.js
- Basado en async/await: Su diseño central gira en torno a
async/await
, permitiendo un control intuitivo del flujo asíncrono. - Núcleo ligero: El núcleo de Koa es muy compacto y solo incluye las funcionalidades básicas, expandiéndose mediante middleware modular.
- Middleware potente: Utiliza un mecanismo de middleware en cascada que permite una gestión clara y flexible de las solicitudes.
- Enfoque web: Está orientado al desarrollo de aplicaciones web y APIs, sin ofrecer funcionalidades superfluas.
El uso de Koa.js permite a los desarrolladores construir servicios web eficientes y fácilmente mantenibles.
Configuración del entorno de desarrollo Koa.js con ServBay
ServBay proporciona un entorno listo para usar para desarrolladores Node.js, integrando el runtime de Node.js y servicios de bases de datos habituales. Aprovechando la funcionalidad de Sitios Web (Website) de ServBay, puedes acceder fácilmente a tus proyectos Koa.js locales mediante dominios personalizados y certificados SSL.
Requisitos previos
Antes de comenzar, asegúrate de completar los siguientes pasos:
- Instala ServBay: Visita el sitio oficial de ServBay para descargar e instalar la última versión.
- Instala el paquete de Node.js: Abre la aplicación ServBay, accede al área de gestión de Paquetes (Packages) y verifica que tienes instalada la versión de Node.js que necesitas. Instala el paquete si aún no lo tienes.
- Familiarízate con ServBay: Conoce el funcionamiento básico para iniciar/detener servicios y gestionar Sitios Web (Website).
Creación de un proyecto Koa.js
Utilizaremos el directorio raíz recomendado por ServBay /Applications/ServBay/www
para almacenar los archivos del proyecto.
Inicializa el directorio del proyecto
Abre la aplicación Terminal y navega al directorio raíz de sitios web de ServBay. Crea una nueva carpeta para tu proyecto (por ejemplo,
servbay-koa-app
), accede a ella e inicializa un proyecto de Node.js:bashcd /Applications/ServBay/www mkdir servbay-koa-app cd servbay-koa-app npm init -y
1
2
3
4El comando
npm init -y
creará automáticamente un archivopackage.json
por defecto.Instalación de Koa.js
Desde el directorio raíz de tu proyecto
servbay-koa-app
, instala Koa.js y sus tipos (si usas TypeScript):bashnpm install koa # Si usas TypeScript, instala los tipos # npm install @types/koa --save-dev
1
2
3Crea el archivo principal de la aplicación
En el directorio principal
servbay-koa-app
, crea un archivo llamadoapp.js
y añade el siguiente código de ejemplo para una aplicación Koa.js básica:javascriptconst Koa = require('koa'); const app = new Koa(); // Middleware: registra información de la solicitud app.use(async (ctx, next) => { const start = Date.now(); await next(); const ms = Date.now() - start; console.log(`${ctx.method} ${ctx.url} - ${ms}ms`); }); // Middleware: maneja las solicitudes a la ruta raíz app.use(async ctx => { ctx.body = 'Hello from ServBay Koa.js App!'; }); // Definir puerto, usar la variable de entorno PORT si existe const port = process.env.PORT || 3000; // Iniciar el servidor HTTP app.listen(port, () => { console.log(`Koa.js server running on http://localhost:${port}`); console.log(`Project path: ${__dirname}`); });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24Este código define una aplicación Koa básica con dos middlewares: uno para registrar el tiempo y la ruta de cada solicitud, y otro para responder a la ruta raíz
/
mostrando "Hello from ServBay Koa.js App!". La aplicación escucha en el puerto definido por la variable de entornoPORT
o el puerto3000
por defecto.
Modo desarrollo
Durante el desarrollo, normalmente ejecutaremos el proceso local de Node.js para la app Koa.js y lo accederemos mediante la funcionalidad de Sitios Web (Website) de ServBay.
Ejecuta el servidor de desarrollo Koa.js
Abre la Terminal, navega al directorio
servbay-koa-app
y ejecuta el archivoapp.js
usandonode
. Para evitar conflictos de puerto y facilitar la configuración en ServBay, se recomienda especificar un puerto, como el8585
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8585 node app.js
1
2En la terminal aparecerá un mensaje como
Koa.js server running on http://localhost:8585
, indicando que el servidor está activo en el puerto8585
. Mantén esta ventana abierta para que la aplicación siga corriendo.Configura el proxy inverso de Sitios Web (Website) en ServBay
Para acceder a tu app Koa.js ejecutándose en
localhost:8585
mediante un dominio propio, configura un Sitio Web (Website) con proxy inverso en ServBay:- Abre la aplicación ServBay.
- Dirígete al apartado Sitios Web (Website).
- Haz clic en el botón
+
para agregar un nuevo sitio web. - Configura los datos del sitio:
- Nombre:
ServBay Koa.js Dev Site
- Dominio:
servbay-koa-dev.servbay.demo
(se recomienda terminar en.servbay.demo
, ServBay generará un certificado SSL automáticamente) - Tipo: selecciona
Proxy Inverso (Reverse Proxy)
- Dirección IP:
127.0.0.1
(apunta al proceso Node.js local) - Puerto:
8585
(el puerto de la app Koa.js) - Directorio raíz: para proxy inverso no aplica, déjalo vacío o pon la ruta
/Applications/ServBay/www/servbay-koa-app
.
- Nombre:
- Guarda la configuración.
- Si ServBay solicita aplicar los cambios, haz clic en aplicar.
Al finalizar, ServBay actualizará automáticamente tu archivo
hosts
local para apuntarservbay-koa-dev.servbay.demo
a127.0.0.1
. Además, las peticiones a ese dominio se redirigirán internamente al puerto8585
mediante Caddy o Nginx integrado. Usando dominio.servbay.demo
, ServBay User CA genera y confía automáticamente el certificado SSL, permitiéndote acceder de forma segura vía HTTPS.Para más detalles, consulta la documentación de ServBay sobre cómo añadir un sitio de desarrollo Node.js (elige la documentación en inglés).
Accede al sitio web de desarrollo Koa.js
Abre el navegador y visita
https://servbay-koa-dev.servbay.demo
.Si todo está configurado correctamente, verás "Hello from ServBay Koa.js App!" en la página. Esto significa que accedes a tu servidor Koa.js local usando el proxy inverso de ServBay, con dominio personalizado y HTTPS. Al editar
app.js
y reiniciar Node.js, verás los cambios tras refrescar el navegador.
Simulación de despliegue en producción
Para simular un entorno de producción, puedes usar diferentes puertos, variables de entorno o métodos de inicio. La configuración de proxy inverso en ServBay es igualmente válida para este escenario.
Ejecuta el servidor en modo producción (simulado)
En otra ventana de Terminal, detén el servidor de desarrollo y arranca la app usando el puerto
8586
y la variableNODE_ENV
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8586 NODE_ENV=production node app.js
1
2Así se simula la ejecución en modo producción, escuchando en
8586
.Configura el proxy inverso para producción en ServBay
Igualmente, crea un nuevo Sitio Web (Website) para la producción simulada:
- Abre ServBay y ve al apartado Sitios Web (Website).
- Haz clic en
+
para añadir el nuevo sitio. - Configura los siguientes datos:
- Nombre:
ServBay Koa.js Prod Site
- Dominio:
servbay-koa-prod.servbay.demo
(o tu propio dominio; ServBay admite certificados SSL gratis vía ACME/Let's Encrypt) - Tipo: selecciona
Proxy Inverso (Reverse Proxy)
- Dirección IP:
127.0.0.1
- Puerto:
8586
(el puerto de producción simulado) - Directorio raíz: vacío o la ruta del proyecto.
- Nombre:
- Guarda y aplica los cambios.
Si usas
.servbay.demo
, seguirás contando con el certificado User CA. Para dominios públicos propios, ServBay soporta certificados SSL/TLS gratis mediante ACME (ejemplo, Let's Encrypt) para simular un entorno real de producción. Consulta la documentación sobre Cómo proteger tu sitio web con SSL.Accede al sitio web de producción (simulado) Koa.js
Abre el navegador y entra en
https://servbay-koa-prod.servbay.demo
.Deberías ver la misma salida que en el entorno de desarrollo, pero esta vez servida por el Node.js ejecutándose en el puerto
8586
atrás del proxy inverso de ServBay.
Conexión a bases de datos
ServBay integra varios sistemas de bases de datos populares: MongoDB, Redis, MariaDB (compatible con MySQL) y PostgreSQL. La conexión desde tus proyectos Koa.js es sencilla, ya que todas corren en local y se acceden habitualmente mediante localhost
.
A continuación verás ejemplos para conectar, desde Node.js, a las bases integradas en ServBay. Antes de usarlos, asegúrate de haber instalado y abierto los servicios correspondientes en ServBay en el área Paquetes (Packages).
Conectar a MongoDB
Primero instala el driver Node.js de MongoDB (
mongoose
omongodb
):bashcd /Applications/ServBay/www/servbay-koa-app npm install mongoose # o npm install mongodb
1
2Agrega el código de conexión en
app.js
u otro módulo:javascript// Usar Mongoose para conectar a MongoDB const mongoose = require('mongoose'); // Por defecto, MongoDB en ServBay no requiere autentificación, puedes elegir el nombre de la base mongoose.connect('mongodb://localhost:27017/servbay-koa-app', { useNewUrlParser: true, useUnifiedTopology: true }) .then(() => console.log('Connected to MongoDB')) .catch(err => console.error('MongoDB connection error:', err)); // Nota: En proyectos reales, el código de conexión suele ubicarse en la lógica de arranque de la app // y solo iniciar el servidor tras conectar exitosamente.
1
2
3
4
5
6
7
8
9
10
11
12
13MongoDB instalado en ServBay generalmente escucha en el puerto
27017
y no requiere usuario/contraseña por defecto. Elige el nombre de la base; si no existe, se crea automáticamente.Conectar a Redis
Instala la librería cliente de Redis para Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install redis
1
2Conecta al servidor Redis:
javascript// Usar el cliente de Redis para conectar const redis = require('redis'); // Crear el cliente, conectando por defecto a localhost:6379 const client = redis.createClient({ url: 'redis://localhost:6379' // Puerto predeterminado Redis en ServBay }); client.on('connect', () => { console.log('Connected to Redis'); }); client.on('error', (err) => { console.error('Redis connection error:', err); }); // Conectar al servidor Redis client.connect(); // Nota: En la práctica, conviene esperar la conexión antes de operar, // por ejemplo usando async/await y client.connect()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21Redis instala en ServBay escucha por defecto en el puerto
6379
y no requiere contraseña inicial.Conectar a MariaDB (MySQL compatible)
MariaDB es un fork de MySQL, con API casi idéntica. ServBay lo provee como paquete, pudiendo usar la aplicación igual que MySQL.
Instala el driver para Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install mariadb # o npm install mysql2 (mayor compatibilidad, recomendado)
1
2Usa el driver
mariadb
:javascript// Usar el cliente mariadb para conectar const mariadb = require('mariadb'); // El usuario root de MariaDB en ServBay tiene por defecto la contraseña 'password' const pool = mariadb.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Asegúrate que existe la base, o cámbialo según tu caso connectionLimit: 5 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB"); conn.release(); // Liberar la conexión al pool }) .catch(err => { console.error("MariaDB connection error:", err); }); // Nota: Obtener conexiones del pool es una operación asíncrona.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22Usando el driver
mysql2
(recomendado):javascript// Usar mysql2 para conectar a MariaDB/MySQL const mysql = require('mysql2/promise'); // Versión con promesas // El usuario root de MariaDB tiene como contraseña 'password' en ServBay const pool = mysql.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Asegúrate que la base existe waitForConnections: true, connectionLimit: 10, queueLimit: 0 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB/MySQL using mysql2"); conn.release(); // Liberar la conexión al pool }) .catch(err => { console.error("MariaDB/MySQL connection error:", err); }); // Nota: La contraseña de root se gestiona y puede consultarse o modificarse desde el área de configuración de bases de datos de ServBay. // Recomendamos no dejar contraseñas en el código en proyectos reales, usa variables de entorno y métodos seguros.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25MariaDB en ServBay escucha en el puerto
3306
. Las credenciales pueden consultarse y cambiarse desde la interfaz de ServBay. Es probable que debas crear la base de datosservbay_koa_app
manualmente usando ServBay, o bien clientes gráficos como TablePlus, DBeaver, etc.Conectar a PostgreSQL
Instala el driver de PostgreSQL para Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install pg
1
2Conexión al servidor PostgreSQL:
javascript// Usar pg para conectar a PostgreSQL const { Pool } = require('pg'); // Usuario por defecto 'user', contraseña 'password' en ServBay const pool = new Pool({ user: 'user', // Usuario predeterminado host: 'localhost', database: 'servbay_koa_app', // Asegúrate de crear la base password: 'password', // Contraseña predeterminada port: 5432, // Puerto por defecto en ServBay }); pool.connect((err, client, done) => { if (err) { console.error('PostgreSQL connection error:', err); return; } console.log('Connected to PostgreSQL'); client.release(); // Liberar la conexión al pool }); // Nota: Las credenciales pueden consultarse y modificarse desde la sección de configuración de ServBay. // Evita dejar contraseñas en el código en proyectos reales.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23PostgreSQL en ServBay usa el puerto
5432
. Las credenciales, así como la gestión de bases de datos, están accesibles desde la interfaz de ServBay; deberás crear la base de datosservbay_koa_app
de forma manual.
Administración de bases de datos en ServBay
Además de conectar desde el código, puedes gestionar las bases provistas en ServBay usando herramientas gráficas. Los servicios de bases de datos suelen estar en 127.0.0.1
o localhost
, con puertos y credenciales consultables desde la GUI de ServBay.
- Consulta/modifica contraseñas por defecto: Ve al paquete de la base deseada en la app ServBay, haz clic en su icono de configuración para ver o cambiar las credenciales de
root
(MariaDB) ouser
(PostgreSQL). - Crea bases y usuarios: Usa clientes como TablePlus, DBeaver, pgAdmin, MongoDB Compass, etc., conecta a los servicios con los datos de ServBay y crea bases, usuarios y tablas mediante comandos SQL o la interfaz gráfica.
Consideraciones importantes
- Conflictos de puerto: Elige puertos para tu app Koa.js (
8585
,8586
, etc.) que no estén usados por otros programas. - Estado de ServBay: Verifica que ServBay y los paquetes necesarios (Node.js y bases de datos) están en ejecución.
- Archivo hosts: ServBay gestiona el archivo
/etc/hosts
automáticamente, pero puedes revisar manualmente si tienes problemas de resolución de dominios. - Firewall: Asegúrate de que el firewall de macOS o cualquiera de terceros no esté bloqueando conexiones de ServBay o Node.js.
- Revisión de logs: Ante problemas, consulta los logs de ServBay y la salida de Node.js en la terminal para diagnosticar.
Preguntas frecuentes (FAQ)
Pregunta: ¿Por qué usar proxy inverso de ServBay para acceder a mi proyecto Koa.js?
Respuesta: El proxy inverso mediante el módulo de sitios de ServBay ofrece varias ventajas:
- Simulación realista: Usar dominios personalizados como
.servbay.demo
o un dominio propio es más parecido a cómo se accede en producción que mediantelocalhost:PORT
. - Soporte SSL: ServBay genera y configura automáticamente certificados SSL (User CA o Let's Encrypt), permitiendo probar HTTPS durante el desarrollo.
- Gestión centralizada: Administra todos tus sitios locales desde un solo lugar con rapidez y comodidad.
- Puertos estandarizados: Los navegadores y visitantes acceden por los puertos estándar (80/443) sin exposición directa a los puertos internos elevados en Node.js.
- Simulación realista: Usar dominios personalizados como
Pregunta: ¿Puedo acceder sin proxy inverso vía
localhost:PORT
?Respuesta: Sí, puedes abrir directamente
http://localhost:PORT
en el navegador para tu Koa.js local, pero no aprovecharás las ventajas de ServBay: dominios personalizados, SSL automático, gestión de logs y otras facilidades para desarrollo y simulación de producción. El uso del proxy inverso es preferible para un entorno más realista.Pregunta: ¿Cuál es la contraseña por defecto de las bases en ServBay? ¿Cómo la cambio?
Respuesta: Las contraseñas por defecto pueden consultarse desde la sección de Bases de Datos de ServBay. Haz clic en el icono de ajustes del paquete correspondiente (MariaDB, PostgreSQL, etc.), y verás las credenciales actuales. Ahí mismo puedes cambiarlas. Por seguridad, se recomienda cambiar la contraseña por defecto.
Conclusión
Siguiendo esta guía has aprendido cómo montar un entorno de desarrollo Koa.js en macOS usando ServBay. Hemos creado una aplicación básica con Koa.js y configurado el acceso mediante proxy inverso en ServBay, usando dominios personalizados y HTTPS, tanto en modo desarrollo como para simular producción. También has visto cómo conectar fácilmente con diferentes bases de datos integradas.
ServBay proporciona a los desarrolladores Node.js un entorno local integrado y gestionable, permitiéndote concentrarte en el desarrollo sin complicaciones de configuración. Aprovecha su potencia para mejorar tu productividad día a día.