Tworzenie i uruchamianie projektu NestJS lokalnie na macOS z użyciem ServBay

NestJS to progresywny framework Node.js do budowy wydajnych i skalowalnych aplikacji serwerowych Node.js. Jest napisany w TypeScript i, inspirowany Angular, wykorzystuje architekturę modułową oraz wzorzec wstrzykiwania zależności (DI). NestJS udostępnia rozbudowane narzędzia, aby ułatwić programistom tworzenie złożonych aplikacji — łatwych w utrzymaniu, testowaniu oraz wysoce odseparowanych.

Najważniejsze cechy i zalety NestJS

• Architektura modułowa: Kod organizowany jest w moduły, co czyni aplikację bardziej czytelną, ustrukturyzowaną i łatwiejszą do zarządzania.
• Wstrzykiwanie zależności: Potężny, intuicyjny system DI znacznie zwiększa testowalność i utrzymanie kodu.
• Wykorzystanie TypeScript: Korzysta z typowania statycznego, interfejsów oraz nowoczesnych funkcji JavaScriptu, zwiększając efektywność i jakość kodu, zmniejszając liczbę błędów w czasie działania.
• Rozbudowane dekoratory: Dekoratory pozwalają definiować kontrolery, serwisy, moduły itd., dzięki czemu kod jest zwięzły, deklaratywny i przejrzysty.
• Bogaty ekosystem: Aktywna społeczność, mnóstwo gotowych modułów i pluginów — łatwa integracja z TypeORM, Mongoose, GraphQL, WebSockets, cache’owaniem, walidacją i innymi funkcjami.
• Oparty o standardy: Bazuje na dojrzałych frameworkach HTTP takich jak Express czy Fastify, oferując wysoką wydajność i kompatybilność.

Korzystając z NestJS, programista może wdrażać najlepsze praktyki backendowe (np. zasady SOLID, wzorce projektowe), by szybko budować wydajne, enterprise'owe aplikacje webowe, API oraz mikrousługi.

Tworzenie i uruchamianie projektu NestJS z ServBay

ServBay to zaawansowane, zintegrowane środowisko lokalnego rozwoju webowego na macOS, zawierające różne wersje Node.js, bazy danych i serwery webowe. W tym przewodniku wykorzystamy środowisko Node.js dostarczane przez ServBay oraz funkcję „stron”, aby utworzyć, uruchomić i skonfigurować projekt NestJS z własną domeną poprzez reverse proxy ServBay.

Wymagania wstępne

Przed rozpoczęciem należy upewnić się, że:

1. Masz zainstalowany ServBay: ServBay jest poprawnie skonfigurowany na Twoim macOS.
2. Node.js jest aktywowany: W zakładce „Pakiety” (Packages) panelu ServBay wybierz i zainstaluj odpowiednią wersję Node.js. Jeśli Node.js nie jest jeszcze dostępny, sprawdź Przewodnik po użyciu Node.js w ServBay.

Tworzenie projektu NestJS

1. Globalna instalacja NestJS CLI

   Otwórz terminal i zainstaluj CLI NestJS za pomocą npm (instalowanego wraz z Node.js):

   npm install -g @nestjs/cli

2. Inicjalizacja projektu

   Przejdź do zalecanego katalogu głównego serwera www w ServBay (/Applications/ServBay/www). To domyślna lokalizacja stron w ServBay — tu warto zakładać nowe projekty dla wygodnej konfiguracji. Następnie utwórz nowy projekt:

   cd /Applications/ServBay/www
   nest new servbay-nest-app

   Po wykonaniu komendy CLI poprowadzi Cię przez zakładanie projektu — m.in. wybierz menadżera paczek (npm, yarn lub pnpm). Dla spójności zalecamy npm. Projekt znajdzie się w /Applications/ServBay/www/servbay-nest-app.

3. Instalacja zależności

   Przejdź do katalogu projektu i doinstaluj wymagane paczki:

   cd servbay-nest-app
   npm install

   Polecenie nest new domyślnie wywołuje npm install, ale ponowne wykonanie zapewnia zaktualizowanie/zainstalowanie wszystkich zależności.

(Opcjonalne) Modyfikowanie odpowiedzi domyślnej projektu NestJS

Aby sprawdzić, czy projekt działa i jest widoczny z ServBay, zmodyfikujmy domyślną odpowiedź na głównym routingu projektu.

1. Edytuj plik src/app.controller.ts

   Otwórz plik src/app.controller.ts w edytorze kodu i zmień zawartość, aby ścieżka główna (/) zwracała tekst „Hello ServBay!”:

   import { Controller, Get } from '@nestjs/common';
   import { AppService } from './app.service'; // Zakładamy, że korzystasz z AppService
   
   @Controller()
   export class AppController {
     constructor(private readonly appService: AppService) {} // Jeśli używasz AppService
   
     @Get()
     getHello(): string {
       // return this.appService.getHello(); // Jeśli używasz AppService
       return 'Hello ServBay!'; // Zwraca tekst bezpośrednio
     }
   }

   Ten kod tworzy prosty kontroler przetwarzający żądania GET na / i zwracający konkretny ciąg znaków.

Uruchamianie projektu NestJS w trybie deweloperskim przez ServBay

NestJS uruchamia się zwykle z wbudowanym serwerem, nasłuchując na określonym porcie. Następnie możesz skonfigurować stronę w ServBay jako reverse proxy, dzięki czemu wybrane domeny będą kierowały ruch na konkretny port Twojej aplikacji.

1. Start serwera deweloperskiego

   W katalogu projektu (/Applications/ServBay/www/servbay-nest-app) uruchom komendę:

   cd /Applications/ServBay/www/servbay-nest-app
   PORT=8585 npm run start:dev

   npm run start:dev to domyślny skrypt w projektach NestJS, korzystający z ts-node oraz automatycznego restartu serwera po zmianie kodu. Aplikacja będzie dostępna na localhost:8585.

2. Konfiguracja reverse proxy w ServBay

   W panelu ServBay przejdź do zakładki „Strony” (Websites). Skonfiguruj nową stronę:

   • Nazwa (Name): np. My first NestJS dev site
   • Domena (Domains): np. servbay-nest-test.dev — ServBay domyślnie obsługuje końcówki takie jak .dev bez edycji pliku hosts.
   • Typ (Type): wybierz Reverse Proxy.
   • Adres IP: zwykle 127.0.0.1
   • Port: 8585, czyli port, na którym działa aplikacja

   Zapisz konfigurację — ServBay automatycznie zaktualizuje ustawienia serwera WWW (Caddy/Nginx). Szczegółowy przewodnik konfiguracji znajdziesz w tworzeniu witryny ServBay.

3. Odwiedzenie strony deweloperskiej

   Otwórz przeglądarkę i wejdź na domenę https://servbay-nest-test.dev.

   Uwaga:

   • ServBay oferuje domyślne bezpłatne certyfikaty SSL (sygnowane przez ServBay User CA), więc możesz korzystać z bezpiecznego https. Jeśli pojawi się ostrzeżenie dotyczące certyfikatu, musisz zaufać ServBay User CA. Po szczegóły zajrzyj do dokumentacji o zabezpieczeniu stron SSL.
   • Upewnij się, że serwer deweloperski NestJS (PORT=8585 npm run start:dev) działa — w przeciwnym razie strona nie będzie dostępna.

Wdrażanie wersji produkcyjnej i dostęp przez ServBay

Przed wdrożeniem do produkcji (nawet na lokalnej maszynie) należy najpierw zbudować projekt.

1. Build wersji produkcyjnej

   Skorzystaj z polecenia:

   cd /Applications/ServBay/www/servbay-nest-app
   npm run build

   Komenda npm run build transpiluje kod TypeScript do katalogu dist.

2. Uruchomienie produkcyjnego serwera

   Po zbudowaniu aplikacji uruchom ją w trybie produkcyjnym (na przykład na porcie 8586) oraz ustaw zmienną środowiskową NODE_ENV=production:

   cd /Applications/ServBay/www/servbay-nest-app
   PORT=8586 NODE_ENV=production node dist/main.js

   W trybie produkcyjnym nie ma już nasłuchiwania zmian w plikach.

3. Reverse proxy do wersji produkcyjnej w ServBay

   Dodaj lub edytuj konfigurację strony w panelu ServBay:

   • Nazwa (Name): np. My first NestJS production site
   • Domena (Domains): np. servbay-nest-test.prod
   • Typ (Type): Reverse Proxy
   • Adres IP: 127.0.0.1
   • Port: 8586 (zgodny z ustawieniami aplikacji)

   Zapisz zmiany.

4. Dostęp do produkcyjnej wersji strony

   Odwiedź w przeglądarce: https://servbay-nest-test.prod. Również tutaj ServBay zapewnia szyfrowanie SSL.

Połączenie z bazami danych w ServBay

ServBay obsługuje wiele baz danych — MariaDB (kompatybilna z MySQL), PostgreSQL, MongoDB i Redis. Podczas rozwoju aplikacji NestJS możesz łatwo z nich korzystać.

Ważne: Upewnij się, że odpowiednia baza danych jest uruchomiona i aktywowana w zakładce „Pakiety” (Packages) panelu ServBay. Domyślne dane dostępowe (port, nazwa użytkownika, hasło) znajdziesz w panelu lub dokumentacji ServBay. W środowisku produkcyjnym stanowczo zalecamy zmianę domyślnych danych oraz tworzenie dedykowanych użytkowników bazodanowych.

Poniżej wybrane przykłady konfiguracji najczęściej używanych ORM/bibliotek w NestJS do podłączenia się do baz danych z ServBay. Te konfiguracje stosuje się najczęściej w głównym module aplikacji (AppModule) lub dedykowanych modułach baz danych.

1. Połączenie z MongoDB

   Użyj @nestjs/mongoose:

   npm install @nestjs/mongoose mongoose

   Konfiguracja w module NestJS:

   import { Module } from '@nestjs/common';
   import { MongooseModule } from '@nestjs/mongoose';
   // ... inne importy
   
   @Module({
     imports: [
       MongooseModule.forRoot('mongodb://localhost:27017/servbay-nest-app'), // Domyślny port 27017
       // ... inne moduły
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   Domyślny connection string MongoDB w ServBay to mongodb://localhost:27017/. By utworzyć bazę servbay-nest-app, skorzystaj np. z MongoDB Compass lub mongosh.

2. Połączenie z Redis

   Użyj @nestjs/redis:

   npm install @nestjs/redis redis @types/redis

   Przykładowa konfiguracja:

   import { Module } from '@nestjs/common';
   import { RedisModule } from '@nestjs/redis';
   // ... inne importy
   
   @Module({
     imports: [
       RedisModule.forRoot({
         url: 'redis://localhost:6379', // Domyślny port 6379
       }),
       // ... inne moduły
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   Domyślny adres Redis to localhost:6379.

3. Połączenie z MariaDB (MySQL)

   Użyj @nestjs/typeorm — ServBay obsługuje MariaDB i MySQL, obie zgodne z tym samym protokołem.

   npm install @nestjs/typeorm mysql2 typeorm

   Przykład konfiguracji:

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... inne importy
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'mariadb', // Lub 'mysql'
         host: 'localhost',
         port: 3306, // Domyślny port
         username: 'root', // Domyślny użytkownik ServBay
         password: 'password', // Domyślne hasło ServBay
         database: 'servbay_nest_app', // Wcześniej utworzona baza
         entities: [], // Twoje encje
         synchronize: true, // Dla developmentu true, w produkcji ostrożnie!
       }),
       // ... inne moduły
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   Uwaga: Domyślne hasło do root to password. Połącz się klientem (TablePlus, DBeaver, MySQL CLI) do localhost:3306, zaloguj się na root/password i utwórz bazę servbay_nest_app. W środowisku produkcyjnym ZAWSZE zmień dane dostępowe oraz utwórz użytkownika o ograniczonych uprawnieniach.

4. Połączenie z PostgreSQL

   Użyj @nestjs/typeorm:

   npm install @nestjs/typeorm pg typeorm

   Przykład konfiguracji:

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   // ... inne importy
   
   @Module({
     imports: [
       TypeOrmModule.forRoot({
         type: 'postgres',
         host: 'localhost',
         port: 5432, // Domyślny port
         username: 'servbay', // Przykładowy użytkownik — sprawdź w panelu
         password: 'password', // Przykładowe hasło
         database: 'servbay_nest_app', // Wcześniej utworzona baza
         entities: [], // Twoje encje
         synchronize: true, // Dla developmentu true, w produkcji ostrożnie!
       }),
       // ... inne moduły
     ],
     controllers: [], // ...
     providers: [], // ...
   })
   export class AppModule {}

   Uwaga: Domyślne konto użytkownika/hasło PostgreSQL może się różnić (najczęściej servbay lub postgres). Sprawdź listę domyślnych poświadczeń w panelu ServBay lub dokumentacji i za pomocą klienta PostgreSQL połącz się do localhost:5432, by utworzyć bazę oraz użytkownika (jeśli to wymagane). W produkcji zawsze zmień domyślne dane dostępowe!

Podsumowanie

W tym przewodniku dowiedziałeś się, jak przy pomocy ServBay szybko tworzyć, uruchamiać oraz obsługiwać projekty NestJS na macOS lokalnie. ServBay integruje środowisko Node.js, łatwą konfigurację stron (w tym reverse proxy) oraz obsługę wielu baz danych, znacząco upraszczając lokalny development i testowanie projektów NestJS. Możesz wygodnie przełączać tryby deweloperski/produkcyjny, używać własnych domen, korzystać z HTTPS oraz łatwo łączyć się z bazami danych zapewnianymi przez ServBay.