Creare e avviare un progetto Koa.js con ServBay
ServBay è un ambiente di sviluppo web locale disponibile per macOS e Windows, che integra vari pacchetti utili per gli sviluppatori, inclusi il runtime Node.js e diversi database. In questo articolo scoprirai come sfruttare l'ambiente integrato di ServBay per creare, avviare e gestire velocemente il tuo progetto Koa.js.
Cos'è Koa.js?
Koa.js è un framework web di nuova generazione basato su Node.js, sviluppato dal team di Express.js. Si distingue per la sua sintassi essenziale, espressiva e dotata di potenti funzionalità, risultando la soluzione ideale per lo sviluppo di applicazioni web e API. Koa.js sfrutta al massimo le caratteristiche moderne di JavaScript, in particolare la sintassi async/await
, semplificando notevolmente la gestione delle operazioni asincrone e la scrittura degli middleware. Il risultato è un codice più pulito e facilmente manutenibile.
Caratteristiche principali di Koa.js
- Basato su async/await: Progettato intorno all’uso di
async/await
, per un controllo dei flussi asincroni più intuitivo. - Core leggero: La libreria di base di Koa è essenziale e include solo le funzioni fondamentali; le feature avanzate si aggiungono tramite middleware modulari.
- Middleware potenti: Gestione dei middleware a cascata, che rende il flusso di gestione delle richieste chiaro e flessibile.
- Focus sul web: Concentrato sullo sviluppo di web app e API, senza funzionalità aggiuntive superflue.
Con Koa.js, gli sviluppatori possono costruire servizi web performanti e manutenibili in modo più efficiente.
Configurare l'ambiente di sviluppo Koa.js con ServBay
ServBay offre agli sviluppatori Node.js un ambiente pronto all’uso, con runtime Node.js e servizi database comuni già integrati. Grazie alla funzione Website di ServBay, puoi facilmente accedere localmente al tuo progetto Koa.js usando un dominio personalizzato e certificati SSL.
Prerequisiti
Prima di iniziare, assicurati di aver completato questi passaggi:
- Installare ServBay: Vai al sito ufficiale ServBay per scaricare e installare l’ultima versione.
- Installare il pacchetto Node.js: Avvia ServBay e accedi alla sezione Packages; verifica di aver installato la versione di Node.js necessaria. In caso contrario, selezionala e procedi con l’installazione.
- Familiarizzare con ServBay: Scopri come avviare/fermare servizi e gestire i Website tramite l’interfaccia di ServBay.
Creazione di un progetto Koa.js
Consigliamo di usare la directory root di ServBay /Applications/ServBay/www
per memorizzare i file di progetto.
Inizializzare la directory del progetto
Apri il Terminale, naviga nella directory root di ServBay, crea una nuova cartella per il progetto (es.
servbay-koa-app
), entra nella cartella e inizializza il progetto Node.js:bashcd /Applications/ServBay/www mkdir servbay-koa-app cd servbay-koa-app npm init -y
1
2
3
4Il comando
npm init -y
genera rapidamente un filepackage.json
di default.Installare Koa.js
Dalla root del progetto
servbay-koa-app
, installa Koa.js (e, se usi TypeScript, le definizioni dei tipi):bashnpm install koa # Se usi TypeScript, aggiungi anche le definizioni dei tipi # npm install @types/koa --save-dev
1
2
3Creazione del file d’ingresso dell’app
Crea un file
app.js
nella directory principale del progetto e aggiungi il seguente codice per una semplice app Koa.js:javascriptconst Koa = require('koa'); const app = new Koa(); // Middleware: registra informazioni sulla richiesta 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: gestisce le richieste alla root app.use(async ctx => { ctx.body = 'Hello from ServBay Koa.js App!'; }); // Definisci la porta, usa l’ambiente PORT se disponibile const port = process.env.PORT || 3000; // Avvia il server 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
24Questo codice crea una semplice applicazione Koa con due middleware: uno per loggare tempo e percorso delle richieste, l’altro per gestire la rotta
/
rispondendo con "Hello from ServBay Koa.js App!". L’applicazione ascolta sulla porta definita dalla variabile d’ambientePORT
o, in mancanza, sulla3000
.
Modalità di sviluppo
Durante lo sviluppo, avvierai localmente un processo Node.js per la tua app Koa.js, e accederai tramite la funzione Website di ServBay.
Avviare il server di sviluppo Koa.js
Apri il Terminale, vai nella directory del progetto
servbay-koa-app
e avviaapp.js
connode
. Per evitare conflitti di porta e facilitare la configurazione ServBay, puoi scegliere una porta specifica come8585
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8585 node app.js
1
2Il terminale mostrerà un messaggio simile a
Koa.js server running on http://localhost:8585
, confermando l’avvio del server sulla porta8585
. Mantieni la finestra del Terminale aperta per farlo funzionare in continuazione.Configurare il reverse proxy Website su ServBay
Per accedere all’app Koa.js tramite un dominio personalizzato sulla porta
8585
, configura un nuovo Website di tipo reverse proxy:- Avvia ServBay.
- Vai sulla sezione Website.
- Premi il pulsante
+
in basso a sinistra per aggiungere un nuovo sito. - Compila la configurazione:
- Nome:
ServBay Koa.js Dev Site
- Dominio:
servbay-koa-dev.servbay.demo
(consigliato il suffisso.servbay.demo
che permette la generazione automatica del certificato SSL) - Tipo: scegli
Reverse Proxy
- Indirizzo IP:
127.0.0.1
(punta al processo Node.js locale) - Porta:
8585
(la porta della tua app Koa.js) - Document Root: non fondamentale per il reverse proxy, può rimanere vuoto o indicare
/Applications/ServBay/www/servbay-koa-app
.
- Nome:
- Salva la configurazione.
- Se richiesto, applica le modifiche.
Al termine, ServBay aggiornerà il file hosts locale, indirizzando
servbay-koa-dev.servbay.demo
verso127.0.0.1
e, tramite i server interni Caddy o Nginx, proxyerà le richieste verso la porta8585
locale. Grazie al dominio.servbay.demo
, ServBay User CA genererà e installerà automaticamente il certificato SSL affinché tu possa accedere in modo sicuro tramite HTTPS.Per istruzioni dettagliate, consulta la documentazione ServBay sull’aggiunta di un sito Node.js di sviluppo (scegli la versione inglese).
Accedere al sito Koa.js di sviluppo
Apri il browser e visita
https://servbay-koa-dev.servbay.demo
.Se tutto è configurato correttamente vedrai la pagina con "Hello from ServBay Koa.js App!". Significa che stai accedendo attivamente al server di sviluppo Koa.js locale tramite ServBay. Modifica
app.js
e riavvia Node.js per vedere eventuali cambiamenti dopo il refresh del browser.
Simulare la modalità produzione
In una simulazione di ambiente produzione potresti usare porte, variabili d’ambiente o opzioni di avvio diverse. La configurazione reverse proxy di ServBay è valida anche in questi casi.
Avviare il server Koa.js in modalità produzione (simulata)
Apri un nuovo Terminale, ferma il server di sviluppo se ancora in esecuzione, quindi avvia l’app come simulazione produzione usando, ad esempio, la porta
8586
e l’ambienteNODE_ENV
:bashcd /Applications/ServBay/www/servbay-koa-app PORT=8586 NODE_ENV=production node app.js
1
2L’app sarà ora accessibile sulla porta
8586
, in una modalità che simula la produzione.Configurare reverse proxy Website per la simulazione produzione
Allo stesso modo, su ServBay crea un nuovo Website:
- Avvia ServBay, vai su Website.
- Premi
+
per aggiungere un sito nuovo. - Compila la configurazione:
- Nome:
ServBay Koa.js Prod Site
- Dominio:
servbay-koa-prod.servbay.demo
(oppure usa il tuo dominio, con ServBay puoi richiedere SSL gratuito da Let's Encrypt) - Tipo:
Reverse Proxy
- IP:
127.0.0.1
- Porta:
8586
(la porta della simulazione produzione) - Document Root: lascia vuoto o indica il percorso progetto.
- Nome:
- Salva e applica.
Usando il dominio
.servbay.demo
si applicherà automaticamente il certificato ServBay User CA. Se usi un dominio pubblico, ServBay supporta la generazione e gestione SSL/TLS gratuiti tramite ACME (Let's Encrypt), avvicinando ancora di più la simulazione alla produzione reale. Consulta la documentazione ServBay relativa alla protezione SSL dei siti.Accedere al sito Koa.js in produzione simulata
Dal browser, visita
https://servbay-koa-prod.servbay.demo
.Vedrai la stessa pagina della modalità sviluppo, ma ora le richieste sono proxyate dalla porta
8586
tramite ServBay.
Collegamento ai database
ServBay integra i principali sistemi database: MongoDB, Redis, MariaDB (compatibile MySQL) e PostgreSQL. Dentro il tuo progetto Koa.js puoi accedere facilmente a questi database che girano localmente e prevedono accesso via localhost
di default.
Ecco alcuni esempi di codice con driver Node.js per la connessione ai database di ServBay. Assicurati che i pacchetti database ServBay siano installati e attivi tramite la sezione Packages.
Collegarsi a MongoDB
Nella cartella del tuo progetto Koa.js, installa il driver Node.js per MongoDB (
mongoose
omongodb
):bashcd /Applications/ServBay/www/servbay-koa-app npm install mongoose # oppure npm install mongodb
1
2Nel file
app.js
(o moduli separati) aggiungi il seguente codice:javascript// Connessione a MongoDB tramite Mongoose const mongoose = require('mongoose'); // MongoDB di default su ServBay non richiede autenticazione 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: Nelle applicazioni reali la connessione andrebbe gestita nella fase di avvio // e il server avviato solo dopo una connessione positiva.
1
2
3
4
5
6
7
8
9
10
11
12
13MongoDB su ServBay ascolta di default sulla porta
27017
, senza necessità di user/password. Specifica semplicemente il nome database (verrà creato se non esiste).Collegarsi a Redis
Installa il client Redis per Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install redis
1
2Collegati al server Redis:
javascript// Connessione a Redis tramite client redis const redis = require('redis'); // Crea il client, di default su localhost:6379 const client = redis.createClient({ url: 'redis://localhost:6379' // Porta predefinita Redis ServBay }); client.on('connect', () => { console.log('Connected to Redis'); }); client.on('error', (err) => { console.error('Redis connection error:', err); }); // Connessione al server Redis client.connect(); // Nota: Nelle applicazioni reali, utilizzare async/await per gestire la connessione // prima di eseguire operazioni su Redis
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21Redis su ServBay utilizza la porta
6379
senza password di default.Collegarsi a MariaDB (MySQL)
MariaDB è un fork di MySQL, pienamente compatibile. ServBay include il pacchetto MariaDB, che puoi usare come MySQL standard.
Installa il driver MariaDB per Node.js:
bashcd /Applications/ServBay/www/servbay-koa-app npm install mariadb # oppure npm install mysql2 (consigliato per maggiore compatibilità)
1
2Connessione tramite
mariadb
:javascript// Connessione a MariaDB tramite client mariadb const mariadb = require('mariadb'); // Password root predefinita: 'password' const pool = mariadb.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Il database deve essere creato in precedenza connectionLimit: 5 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB"); conn.release(); // Rilascia la connessione al pool }) .catch(err => { console.error("MariaDB connection error:", err); }); // Nota: L’ottenimento della connessione dal pool è asincrono
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22Connessione tramite
mysql2
(consigliato):javascript// Connessione a MariaDB/MySQL tramite client mysql2 (Promise-based) const mysql = require('mysql2/promise'); // Password root predefinita: 'password' const pool = mysql.createPool({ host: 'localhost', user: 'root', password: 'password', database: 'servbay_koa_app', // Database da creare anticipatamente waitForConnections: true, connectionLimit: 10, queueLimit: 0 }); pool.getConnection() .then(conn => { console.log("Connected to MariaDB/MySQL using mysql2"); conn.release(); // Rilascia la connessione al pool }) .catch(err => { console.error("MariaDB/MySQL connection error:", err); }); // Nota: La password root può essere visualizzata e modificata nel pannello database di ServBay. // Per sicurezza, preferisci gestire le password tramite variabili d’ambiente.
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 su ServBay ascolta sulla porta
3306
. La password di default per l’utente root è disponibile nel pannello di gestione database. Potresti dover creare manualmente il databaseservbay_koa_app
tramite ServBay o client desktop come TablePlus, DBeaver ecc.Collegarsi a PostgreSQL
Installa il driver Node.js per PostgreSQL:
bashcd /Applications/ServBay/www/servbay-koa-app npm install pg
1
2Connessione al server PostgreSQL:
javascript// Connessione a PostgreSQL tramite client pg const { Pool } = require('pg'); // Utente 'user' e password 'password' di default const pool = new Pool({ user: 'user', // Utente predefinito ServBay host: 'localhost', database: 'servbay_koa_app', // Assicurati che il database esista password: 'password', // Password predefinita ServBay port: 5432, // Porta PostgreSQL predefinita }); pool.connect((err, client, done) => { if (err) { console.error('PostgreSQL connection error:', err); return; } console.log('Connected to PostgreSQL'); client.release(); // Rilascia la connessione al pool }); // Nota: La password e l’utente sono visibili e modificabili dal pannello database ServBay. // Meglio non codificare le password direttamente nel codice.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23PostgreSQL su ServBay gira sulla porta
5432
. Le credenziali di default sono modificabili nel pannello database ServBay e il database va creato manualmente se non esiste.
Gestire i database in ServBay
Oltre alla connessione tramite codice, puoi usare client grafici per collegarti ai database ServBay. Tutti i servizi database sono locali (127.0.0.1 / localhost), user/password e porta sono visibili nel pannello GUI di ServBay.
- Visualizzare/modificare la password di default: Clicca sull’icona impostazioni accanto al database desiderato nel pannello ServBay per vedere o modificare le credenziali.
- Creare database/utenti: Usa strumenti come TablePlus, DBeaver, pgAdmin, MongoDB Compass per collegarti e gestire database, utenti e tabelle via SQL o interfaccia grafica.
Attenzione
- Conflitti di porta: Assicurati che la porta scelta per Koa.js (es. 8585, 8586) non sia già usata da altri programmi.
- Stato di ServBay: Verifica che ServBay e tutti i pacchetti Node.js/database siano attivi.
- File hosts: ServBay gestisce automaticamente il file
hosts
, ma se ci sono problemi di risoluzione dominio, controlla/etc/hosts
per la presenza delle entry corrette. - Firewall: Verifica che firewall macOS o di terze parti non blocchino ServBay o Node.js.
- Log: In caso di problematiche, consulta i log di ServBay (scheda apposita nella GUI) e le uscite del Terminale Node.js per diagnosticare.
Domande Frequenti (FAQ)
Domanda: Perché usare il reverse proxy di ServBay per accedere al mio progetto Koa.js?
Risposta: L’utilizzo del reverse proxy tramite la funzione Website di ServBay offre diversi vantaggi:
- Simulazione ambiente produzione: Accedi al sito tramite un dominio personalizzato (es.
.servbay.demo
o dominio personale) invece dilocalhost:PORT
, simulando meglio l’accesso reale. - Supporto SSL: ServBay configura automaticamente certificati SSL (User CA o Let's Encrypt) per i tuoi siti locali, permettendo test HTTPS anche in sviluppo.
- Gestione centralizzata: Puoi amministrare tutti i tuoi siti di sviluppo da un’unica interfaccia comoda.
- Port hiding: L’accesso avviene su porte standard 80/443, mentre il reverse proxy inoltra internamente alle porte Node.js dedicate.
- Simulazione ambiente produzione: Accedi al sito tramite un dominio personalizzato (es.
Domanda: Posso evitare il reverse proxy e accedere direttamente via
localhost:PORT
?Risposta: Sì. Puoi accedere al tuo Koa.js localmente tramite
http://localhost:PORT
per sviluppo e test. Tuttavia, in questo modo perdi il supporto di ServBay per i domini personalizzati, l’SSL automatico e la gestione avanzata dei log. Per simulare meglio la produzione è consigliato utilizzare il reverse proxy di ServBay.Domanda: Qual è la password predefinita dei database di ServBay? Come la cambio?
Risposta: Trovi le password predefinite nel pannello Database di ServBay. Basta cliccare sull’icona impostazioni accanto al database desiderato per vedere username e password correnti, e modificarle all’occorrenza. Per sicurezza, consigliamo sempre di cambiarla.
Conclusioni
Dopo questa guida, dovresti essere in grado di installare e configurare un ambiente di sviluppo Koa.js su macOS usando ServBay, creare una semplice applicazione Koa.js e configurarla tramite funzione Website per abilitare reverse proxy, dominio personalizzato e HTTPS. Inoltre, hai imparato a collegare il tuo progetto ai principali database locali forniti da ServBay.
ServBay fornisce agli sviluppatori Node.js un ambiente integrato e facile da gestire, consentendo di concentrarsi sulla scrittura del codice invece che sulle configurazioni tecniche. Sfrutta le sue capacità e scoprirai come il tuo lavoro può diventare più veloce ed efficace!