Crear y ejecutar un proyecto Koa.js con ServBay
ServBay es un entorno de desarrollo web local diseñado específicamente para macOS, que integra una variedad de paquetes comunes para desarrolladores, incluyendo el runtime de Node.js y diferentes bases de datos. En este artículo se muestra cómo aprovechar el entorno conveniente que ofrece ServBay para crear, ejecutar y gestionar rápidamente tus proyectos de Koa.js.
¿Qué es Koa.js?
Koa.js es el framework web de última generación para Node.js, desarrollado por el mismo equipo detrás de Express.js. Destaca por su sencillez, expresividad y un potente set de características, lo que lo convierte en una opción ideal para construir aplicaciones web y APIs. Koa.js saca provecho de las capacidades modernas de JavaScript, especialmente la sintaxis async/await
, simplificando en gran medida la escritura de código asíncrono y middlewares, y facilitando su mantenimiento y claridad.
Características principales de Koa.js
- Basado en async/await: Su diseño está centrado en
async/await
, haciendo que el control del flujo asíncrono sea más intuitivo. - Núcleo minimalista: Su librería central es muy ligera e incluye únicamente las funcionalidades básicas; se expande fácilmente mediante middlewares modulares.
- Middleware potente: Adopta una arquitectura de middlewares en cascada, que ofrece un flujo de procesamiento de peticiones claro y flexible.
- Enfoque en la web: Específicamente diseñado para aplicaciones web y APIs, sin añadir funcionalidades innecesarias.
Con Koa.js, los desarrolladores pueden construir servicios web eficientes y de alto rendimiento de forma sencilla y mantenible.
Configuración del entorno de desarrollo Koa.js con ServBay
ServBay provee un entorno listo para Node.js, integrando el runtime y servicios de bases de datos esenciales. Junto con la función de Sitio web (Website) de ServBay, puedes acceder fácilmente a tu proyecto local de Koa.js usando dominios personalizados y certificados SSL.
Requisitos previos
Antes de empezar, asegúrate de lo siguiente:
- Instala ServBay: Accede al sitio oficial de ServBay para descargar e instalar la versión más reciente.
- Instala el paquete de Node.js: Abre la aplicación ServBay, entra en la gestión de Paquetes (Packages) y comprueba que tienes instalada la versión de Node.js necesaria. Si no es así, selecciónala y haz clic en instalar.
- Familiarízate con ServBay: Aprende cómo arrancar/detener servicios y cómo gestionar sitios web (Website) en ServBay.
Creando 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 de ServBay. Luego, crea una nueva carpeta para el proyecto (por ejemplo,
servbay-koa-app
), accede a ella e inicializa un proyecto nuevo 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
generará rápidamente un archivopackage.json
predeterminado.Instala Koa.js
En el directorio raíz que creaste para el proyecto, instala Koa.js y (si utilizas TypeScript) sus definiciones de tipos:
bashnpm install koa # Si utilizas TypeScript, puedes instalar las definiciones de tipos # npm install @types/koa --save-dev
1
2
3Crea el archivo de entrada de la aplicación
Crea un archivo llamado
app.js
en la carpeta de tu proyecto y agrega un código básico de una aplicación Koa.js: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: gestiona las peticiones a la ruta raíz app.use(async ctx => { ctx.body = '¡Hola desde ServBay Koa.js App!'; }); // Define el puerto, usando la variable de entorno PORT si existe const port = process.env.PORT || 3000; // Inicia el servidor HTTP app.listen(port, () => { console.log(`Servidor Koa.js ejecutándose en http://localhost:${port}`); console.log(`Ruta del proyecto: ${__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 crea una aplicación básica de Koa, con dos middlewares: uno que registra el tiempo y la ruta de cada petición, y otro que responde a la ruta
/
con el texto "¡Hola desde ServBay Koa.js App!". La aplicación escuchará en el puerto definido por la variable de entornoPORT
o el puerto 3000 por defecto.
Entra en modo desarrollo
Durante el desarrollo, suele iniciarse el proceso local de Node.js para ejecutar la app y acceder a ella a través de la funcionalidad Sitio web (Website) de ServBay.
Ejecuta el servidor de desarrollo Koa.js
Abre Terminal, ingresa al directorio del proyecto y ejecuta el archivo
app.js
con Node. Para evitar conflictos de puerto y facilitar la configuración de ServBay, puedes definir un puerto específico, por ejemplo8585
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8585 node app.js
1
2Verás en terminal un mensaje similar a
Servidor Koa.js ejecutándose en http://localhost:8585
, indicando que la aplicación está corriendo y escuchando en ese puerto. Deja abierta esa ventana para mantener el servidor activo.Configura el proxy inverso en Sitio web de ServBay
Para acceder al servidor Koa.js en
localhost:8585
desde un dominio personalizado, debemos crear un nuevo Sitio web (Website) en ServBay configurado como proxy inverso:- Abre la aplicación de ServBay.
- Dirígete al apartado Sitio web (Website).
- Haz clic en el botón
+
en la esquina inferior izquierda para añadir un nuevo sitio. - Rellena los datos:
- Nombre:
ServBay Koa.js Dev Site
- Dominio:
servbay-koa-dev.servbay.demo
(se recomienda el sufijo.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 de Node.js local) - Puerto:
8585
(el mismo que tu aplicación Koa.js) - Raíz de documentos (Document Root): este campo no es relevante para el proxy inverso; déjalo vacío o puedes poner la ruta del proyecto
/Applications/ServBay/www/servbay-koa-app
.
- Nombre:
- Haz clic en guardar.
- Si ServBay solicita aplicar cambios, acepta para actualizar la configuración.
Tras esto, ServBay actualizará el archivo hosts, asociando
servbay-koa-dev.servbay.demo
a127.0.0.1
, y mediante su servidor integrado (Caddy o Nginx) canalizará las peticiones de ese dominio al puerto8585
. Además, como pertenece al dominio.servbay.demo
, ServBay User CA generará y confiará automáticamente un certificado SSL, así que podrás acceder de forma segura usando HTTPS.Si deseas detalles adicionales, consulta la documentación de ServBay sobre añadir un sitio de desarrollo Node.js (elige la versión en inglés).
Accede al sitio de desarrollo Koa.js
Abre tu navegador y accede a
https://servbay-koa-dev.servbay.demo
.Si todo está correctamente configurado, deberías ver el mensaje "¡Hola desde ServBay Koa.js App!". Esto confirma que tu navegador accede a tu servidor de desarrollo Koa.js local a través del proxy de ServBay. Cada vez que modifiques
app.js
y reinicies el proceso de Node, los cambios aparecerán tras refrescar la página.
Despliegue de la versión de producción (simulación)
Cuando quieras simular un entorno de producción, puedes utilizar un puerto, variables de entorno o métodos de arranque distintos. La configuración de proxy en ServBay es igualmente válida para este contexto.
Ejecuta el servidor Koa.js en modo producción (simulado)
En una nueva terminal (o tras detener el servidor de desarrollo), ejecuta el proyecto simulando el entorno de producción, por ejemplo usando el puerto
8586
y configurando la variableNODE_ENV
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8586 NODE_ENV=production node app.js
1
2Esto levantará otra instancia de Koa.js, escuchando el puerto
8586
y simulando el modo de producción.Configura un sitio web en ServBay para producción (simulado)
Repite los pasos en ServBay, creando un nuevo sitio para el entorno simulado de producción:
- Abre ServBay y ve al apartado Sitio web (Website).
- Haz clic en el botón
+
para añadir un sitio nuevo. - Configura los campos así:
- Nombre:
ServBay Koa.js Prod Site
- Dominio:
servbay-koa-prod.servbay.demo
(o tu propio dominio; si usas un dominio tuyo, puedes solicitar un certificado SSL gratuito con Let's Encrypt desde ServBay) - Tipo: selecciona
Proxy inverso (Reverse Proxy)
- Dirección IP:
127.0.0.1
- Puerto:
8586
(el del servidor de producción Koa.js) - Raíz de documentos: vacío o la ruta del proyecto.
- Nombre:
- Guarda y aplica los cambios.
Si utilizas un dominio
.servbay.demo
, seguirás usando el certificado de ServBay User CA. Si optas por tu dominio público, ServBay soporta certificados ACME/Let's Encrypt fácilmente. Más información en la documentación de ServBay sobre proteger tu sitio web con SSL.Accede al sitio Koa.js de producción (simulada)
Abre el navegador y ve a
https://servbay-koa-prod.servbay.demo
.La salida será idéntica a la del desarrollo, pero ahora las peticiones son canalizadas por ServBay hacia el proceso Node.js escuchando en el puerto
8586
.
Conexión con bases de datos
ServBay integra sistemas de base de datos populares como MongoDB, Redis, MariaDB (compatible con MySQL) y PostgreSQL. Es sencillo conectarlas en tu proyecto Koa.js, ya que se ejecutan localmente y puedes acceder a ellas usando localhost
con la configuración predeterminada.
A continuación, encontrarás ejemplos básicos usando los drivers de Node.js para las bases de datos incluidas. Asegúrate de que la base de datos correspondiente esté instalada y ejecutándose desde la sección Paquetes (Packages) de ServBay.
Conectando a MongoDB
Instala el driver Node.js para MongoDB (por ejemplo
mongoose
omongodb
):bashcd /Applications/ServBay/www/servbay-koa-app npm install mongoose # o npm install mongodb
1
2Luego, añade este código en
app.js
u otro módulo:javascript// Conectando a MongoDB usando Mongoose const mongoose = require('mongoose'); // Por defecto, MongoDB en ServBay no requiere autenticación; base de datos personalizable mongoose.connect('mongodb://localhost:27017/servbay-koa-app', { useNewUrlParser: true, useUnifiedTopology: true }) .then(() => console.log('Conectado a MongoDB')) .catch(err => console.error('Error al conectar a MongoDB:', err)); // Nota: En apps reales, la conexión suele estar en la lógica de lanzamiento de la app // y escuchar en el puerto después del éxito en la conexión.
1
2
3
4
5
6
7
8
9
10
11
12
13El servicio MongoDB de ServBay escucha el puerto
27017
y, generalmente, permite conexiones sin credenciales. Solo especifica el nombre de la base de datos (si no existe, se creará automáticamente).Conectando a Redis
Instala la librería cliente de Redis:
bashcd /Applications/ServBay/www/servbay-koa-app npm install redis
1
2Y conecta la app:
javascript// Conectando a Redis usando el cliente redis const redis = require('redis'); // Crea el cliente Redis (por defecto en localhost:6379) const client = redis.createClient({ url: 'redis://localhost:6379' // Puerto por defecto en ServBay }); client.on('connect', () => { console.log('Conectado a Redis'); }); client.on('error', (err) => { console.error('Error de conexión a Redis:', err); }); // Conecta el cliente client.connect(); // Nota: Es recomendable esperar a la conexión antes de ejecutar operaciones, // por ejemplo, usando async/await junto con client.connect()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21Redis en ServBay escucha en el puerto
6379
y no requiere contraseña por defecto.Conectando a MariaDB (o MySQL)
MariaDB es un fork de MySQL y compatible a nivel de API; ServBay incluye el paquete oficial. Puedes usarlo como si fuera MySQL.
Instala el driver correspondiente:
bashcd /Applications/ServBay/www/servbay-koa-app npm install mariadb # o npm install mysql2 (alta compatibilidad, recomendado)
1
2Conectando con
mariadb
:javascript// Conectando a MariaDB usando el cliente mariadb const mariadb = require('mariadb'); // Por defecto, root:password son las credenciales en ServBay const pool = mariadb.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Asegúrate de crear la base de datos previamente connectionLimit: 5 }); pool.getConnection() .then(conn => { console.log("Conectado a MariaDB"); conn.release(); // Libera la conexión al pool }) .catch(err => { console.error("Error de conexión a MariaDB:", 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
22Con
mysql2
(recomendado):javascript// Conectando a MariaDB/MySQL usando mysql2 const mysql = require('mysql2/promise'); // Compatibilidad con promesas // Por defecto, root:password en ServBay const pool = mysql.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Previamente creada waitForConnections: true, connectionLimit: 10, queueLimit: 0 }); pool.getConnection() .then(conn => { console.log("Conectado a MariaDB/MySQL usando mysql2"); conn.release(); // Libera la conexión al pool }) .catch(err => { console.error("Error de conexión a MariaDB/MySQL:", err); }); // Nota: La contraseña predeterminada de root se puede revisar y cambiar desde el GUI de ServBay. // Se recomienda usar variables de entorno para las contraseñas y evitar hardcodearlas.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25El servicio MariaDB por defecto escucha en el puerto
3306
. Encuentra o cambia las credenciales en el apartado administración de base de datos. Puede que necesites crear previamente la base de datos con un cliente como TablePlus, DBeaver, etc.Conectando a PostgreSQL
Instala el driver oficial Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install pg
1
2Conexión básica:
javascript// Conectando a PostgreSQL usando el cliente pg const { Pool } = require('pg'); // Por defecto, user:password en ServBay const pool = new Pool({ user: 'user', host: 'localhost', database: 'servbay_koa_app', // Debe existir previamente password: 'password', // Contraseña por defecto en ServBay port: 5432, // Puerto PostgreSQL por defecto }); pool.connect((err, client, done) => { if (err) { console.error('Error de conexión a PostgreSQL:', err); return; } console.log('Conectado a PostgreSQL'); client.release(); // Libera el cliente al pool }); // Nota: Puedes ver o cambiar la contraseña del usuario 'user' desde el GUI de ServBay. // Se recomienda no guardar passwords directamente en el código.
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 escucha en el puerto
5432
. Credenciales y datos pueden gestionarse desde el GUI. Recuerda crear la baseservbay_koa_app
previamente si no existe.
Gestión de bases de datos en ServBay
Además de conectar mediante código, puedes administrar las bases de datos de ServBay con herramientas gráficas. Las bases corren en 127.0.0.1
/localhost
y puedes usar los puertos y credenciales que ServBay muestra en la interfaz.
- Ver/modificar contraseñas: En la aplicación ServBay, encuentra el paquete de la base de datos, haz clic en el ícono de configuración y consulta o cambia las credenciales (usuario root de MariaDB, user de PostgreSQL, etc.).
- Crear bases de datos y usuarios: Usa clientes como TablePlus, DBeaver, pgAdmin, MongoDB Compass, etc., conectándote a las instancias locales, para crear bases, tablas, usuarios y administrar datos fácilmente por interfaz o comandos SQL.
Notas importantes
- Conflicto de puertos: Usa puertos (p.ej. 8585, 8586) que no estén ya en uso por otros programas.
- Estado de ServBay: Asegúrate de que ServBay, el paquete de Node.js y las bases de datos necesarias estén bien ejecutándose.
- Archivo hosts: ServBay lo gestiona automáticamente, pero si tienes problemas de resolución de dominios, revisa que existan los registros apropiados en
/etc/hosts
. - Cortafuegos: Comprueba que el firewall de macOS o externos no bloquean el acceso de ServBay o los procesos de Node.js.
- Revisión de logs: Si surge algún inconveniente, revisa los logs de ServBay (en la pestaña correspondiente) y la salida del proceso Node.js en la terminal, te ayudarán en el diagnóstico.
Preguntas frecuentes (FAQ)
¿Por qué usar el proxy inverso de ServBay para acceder a mi proyecto Koa.js?
Respuesta: El proxy inverso de los sitios web en ServBay ofrece varias ventajas:
- Simulación de entorno real: Acceder mediante tu propio dominio (como
.servbay.demo
o uno propio) se parece más al entorno de producción que usarlocalhost:PUERTO
. - Soporte SSL: ServBay puede crear y gestionar certificados SSL para sitios locales (usando ServBay User CA o Let's Encrypt), facilitando pruebas con HTTPS incluso en desarrollo.
- Gestión centralizada: Puedes administrar todos tus sitios y entornos de desarrollo desde la interfaz de ServBay de forma rápida y cómoda.
- Ocultamiento de puertos: El navegador accede mediante los puertos estándar 80/443, facilitando incluso el acceso externo si lo habilitas, y ServBay redirige internamente a los puertos altos del proceso Node.js.
- Simulación de entorno real: Acceder mediante tu propio dominio (como
¿Puedo acceder directamente a
localhost:PUERTO
sin proxy inverso?Respuesta: Sí, puedes. Si tu app Koa.js escucha en un puerto específico (por ejemplo, 3000 o el que configures), puedes acceder mediante
http://localhost:PUERTO
. Sin embargo, perderías ventajas como dominios personalizados, SSL automático y la gestión centralizada de logs y accesos de ServBay. Para una experiencia más cercana a producción, se recomienda usar el proxy inverso.¿Cuál es la contraseña predeterminada de las bases de datos en ServBay y cómo cambiarla?
Respuesta: Las contraseñas predeterminadas para las bases instaladas se pueden ver en la sección Base de datos de la app ServBay. Haz clic en el ícono de configuración junto a la base correspondiente (p.ej., MariaDB, PostgreSQL) para consultar o cambiar los usuarios y contraseñas. Por seguridad, se recomienda cambiar la contraseña predeterminada.
Resumen
Siguiendo esta guía has aprendido cómo montar un entorno Koa.js usando ServBay en macOS. Has creado una aplicación básica, configurado el proxy inverso de ServBay para acceder mediante dominio personalizado y HTTPS tanto en desarrollo como en simulación de producción, y comprendido cómo conectar con las bases de datos integradas.
ServBay brinda a los desarrolladores Node.js un entorno local integrado y fácil de gestionar, ayudándote a centrarte en el código sin complicaciones de configuración. Aprovecha la potencia de ServBay para potenciar y agilizar tu flujo de desarrollo.