Wróć do strony głównej
Angular

Bezproblemowe wdrażanie aplikacji Angularowej z użyciem Vercel

Angular + Vercel

Jeżeli dopiero zaczynasz przygodę z Angularem, z pewnością chciałbyś mieć możliwość udostępnienia swoich projektów na zewnątrz. W oficjalnej dokumentacji, możemy znaleźć kilka receptur na deployment aplikacji za pomocą serwisów typu Firebase, Github Pages lub Netlify. Każdy z wymienionych serwisów ma swój własny proces wdrażania aplikacji. W nadchodzącej serii artykułów przeanalizujemy niektóre z nich. Dzisiaj pod lupę weźmiemy jedną z opcji jaką jest Vercel.

Vercel

Vercel to potężna platforma do wdrażania aplikacji webowych. Oferuje nam szereg ciekawych funkcjonalności, które przeanalizuję w dalszej części. Vercel słusznie kojarzy się głównie ze swoim meta-frameworkiem Next.js, bazującym na bibliotece React. Nie oznacza to jednak, że nie możemy wdrożyć aplikacji napisanej w innych technologiach, np. w Angularze. Vercel w swojej ofercie ma darmowy plan hobby, który świetnie sprawdzi się do naszych side projectów.

Tworzenie aplikacji

Na samym początku wygenerujmy nową aplikację za pomocą Angular CLI. Zamiast standardowego npm’a użyję pnpm jako package managera. Pnpm jest alternatywą dla npm’a, która oferuje nam szybszą instalacje paczek oraz lepszą wydajność. W przypadku późniejszego deployowania aplikacji, będzie zależało nam na czasie budowania, dlatego jest to niewątpliwie zaleta. Możemy to zrobić dodając flagę --package-manager={npm|yarn|pnpm|cnpm} do naszej komendy.

Deploy z Vercel CLI

Projekt stworzony. Aby wdrożyć nasz projekt na Vercel możemy połączyć naszą aplikację z repozytorium na popularnych platformach, jak np. Github lub za pomocą Vercel CLI. Do podstawowego korzystania z platformy, połączenie zdalnego repozytorium w pełni wystarczy. Instalujemy Vercel CLI jako globalną paczkę w pnpm.

Po instalacji możemy zweryfikować czy paczka została poprawnie zainstalowana.

Vercel CLI zainstalowane, możemy teraz przejść do wdrożenia naszej aplikacji. Z poziomu głównego katalogu uruchamiamy komendę vercel, która uruchomi konfigurator naszego projektu na platformie. Jeżeli nigdy wcześniej nie używaliśmy Vercel CLI, zostaniemy poproszeni o zalogowanie się do naszego konta.

Jak widać, Vercel automatycznie wykrył naszą aplikację jako Angularową i zainicjował konfigurację z gotowego presetu. W outpucie dostaliśmy linki do naszego środowiska produkcyjnego aplikacji oraz odnośnik do naszego projektu na Vercelu.

Zróbmy teraz prostą zmianę w kodzie i zobaczmy jak wygląda proces deployowania aplikacji przy użyciu komendy vercel deploy

Vercel dla każdego deploymentu tworzy nam środowisko preview, które możemy przetestować przed wdrożeniem na produkcję. Możemy sprawdzić zmiany przez wizualny podgląd, a następnie przerzucić je na środowisko produkcyjne, jak podpowiedziało wyżej CLI. W tym celu wystarczy wywołać komendę vercel --prod.

Połączenie z repozytorium na GitHubie

W poprzednim kroku połączyliśmy lokalną aplikacje z Vercelem. Warto dodać, że Vercel oferuje nam możliwość deployowania aplikacji bezpośrednio z repozytorium na popularnych platformach, takich jak GitHub, GitLab, Bitbucket. Jest to zdecydowanie wygodniejsze rozwiązanie.

W panelu na stronie Vercela przechodzimy do nowo utworzonego projektu.   

Na górze mamy przycisk, który przeniesie nas do ustawień projektu wraz z listą dostępnych repozytoriów konta, które powiązaliśmy z Vercelem.

Od teraz, każdy push do repozytorium uruchomi automatyczny proces deployowania aplikacji.

Comments

Jak widzimy, deployment aplikacji jest bajecznie prosty. Po wejściu na preview url, możemy dostrzec dodatkowy, statyczny panel w dolnej sekcji naszej strony.

Jest to dedykowana dla platformy nakładka, dzięki której możemy między innymi umieszczać komentarze przypinając je do danej sekcji strony. Jest to świetne narzędzie do dyskusji i dzielenia się uwagami z zespołem. Jest w pełni interaktywna – możemy tagować innych użytkowników, tworzyć wątki oraz dostawać notyfikację. Dla darmowego planu hobby może służyć jako notatki. Gdyby panel w jakikolwiek sposób nam przeszkadzał, możemy go ukryć lub w pełni wyłączyć ten feature w ustawieniach.

Vercel Integrations

Są to gotowe integracje z różnymi zewnętrznymi, a także wewnętrznymi serwisami i narzędziami. Do wyboru mamy przeróżne opcje w postaci popularnych narzędzi do monitoringu, analityki, CMS i wiele więcej. Ilość integracji stale rośnie, więc jeżeli nie znajdziesz swojego ulubionego narzędzia, być może pojawi się w niedalekiej przyszłości! https://vercel.com/integrations

Jako pierwszą integracje, do swojego projektu dodam Vercel Analytics. Na dzień pisania artykułu Analytics jest w fazie Beta, przez co jest darmowy. Może się to zmienić w przyszłości. Włącza się go nietypowo w porównaniu do reszty integracji, bo w głównym panelu naszego projektu, w zakładce “Analytics”. Poniżej możemy skonfigurować Web Vitals lub Audiences. My zajmiemy się zakładką “Audiences”, czyli ubogim Google Analyticsem do pobierania podstawowych metryk, takich jak liczba wejść na strony, ich źródła oraz liczba odwiedzających. Po wejściu w zakładkę, uruchamiamy moduł przyciskiem “Enable”.

Zliczanie statystyk musimy zacząć od instalacji oficjalnej paczki: 

Teraz wystarczy dodać funkcję inicjalizującą skrypt analityczny w procesie bootstrapu naszej aplikacji. Dodajemy więc odpowiedni kawałek kodu do naszej aplikacji w pliku main.ts.

Po odpaleniu aplikacji, zobaczymy w konsoli logi z prefixem [Vercel Analytics], służące do debugowania zdarzeń pobieranych przez skrypt. Debugowanie jest włączone automatycznie jeżeli zmienna środowiskowa NODE_ENV ma wartość developement lub test, natomiast możemy je wyłączyć dodając odpowiednią flagę w propsach injecta:

Dodatkowo możemy zauważyć, że funkcja dodała do dokumentu skrypt Vercela na końcu head’a:

Oznacza to, że wszystko działa jak należy! Commitujemy, pushujemy i sprawdzamy deployment! Po testowych wejściach na produkcyjny link, wracamy do panelu i możemy potwierdzić, że dane odkładają się prawidłowo. 

Analytics jest jedną z podstawowych integracji, do innych jeszcze wrócimy ?

Serverless Functions

Vercel oferuje tworzenie serverless functions z poziomu projektu, które zostaną automatycznie zmapowane i wdrożone przy regularnym deploymencie apki. Za moment sprawdzimy jak prosty jest proces ich tworzenia.

W darmowym planie Hobby, możemy stworzyć maksymalnie 12 funkcji. Dostajemy również limit maksymalnego czasu wykonywania wynoszący 10 sekund.

Dla szybszego czasu otrzymania odpowiedzi z naszych funkcji, sprawdźmy region deploymentu w ustawieniach projektu w panelu. Miałem ustawioną domyślną lokalizację ze Stanów Zjednoczonych, dlatego zmieniam na najbliższy dla mnie Frankfurt.

Zabawę z vercelowymi funkcjami zaczynamy od instalacji paczek. Będą to definicje typów.

W naszym głównym katalogu tworzymy folder api. Każdy plik *.js/*.ts utworzony w tym folderze zostanie zinterpretowany jako serverless function oraz zmapowany na adres identyczny jak nazwa pliku.

Oznacza to, że utworzenie pliku o nazwie cats.ts zbuduje nam endpoint o ścieżce /api/cats . Wyjątkiem jest plik o nazwie index , który definiowany jest jako punkt dostępowy bieżącego katalogu. Umieszczając plik index.ts w folderze dogs, ścieżka naszego endpointu będzie wyglądała tak: /api/dogs.

Stwórzmy więc nasz pierwszy endpoint w pliku o nazwie hello.ts. Dla przypomnienia, zostanie on zmapowany do ścieżki /api/hello.  

Do funkcji przekazywany jest request oraz response, co pozwala nam na dostęp do cookies, query parameters i innych właściwości interfejsu RequestW podobny sposób tworzylibyśmy endpoint w bibliotece typu express.js. Jak możemy wywnioskować z kodu, mutujemy response zwracając status 200 wraz z odpowiedzią w postaci obiektu z polem ‘message’.

Aby uniknąć błędów kompilacji plików typescript, dodajmy tsconfig.json wewnątrz folderu api.

Standardowe serwowanie aplikacji przez komendę ng serve nie wystarczy do uruchomienia naszej funkcji, ponieważ angularowy builder nie ma pojęcia o istnieniu i mechanizmie katalogu api. Vercel CLI oferuje dedykowany serwer lokalny, który wrapuje komendy z Angularowego CLI i jednocześnie imituje działanie serverless functions uruchamiając je na dodatkowym procesie. Uruchamiamy go komendą</span><span style="font-weight: 400">vercel dev. Serwer domyślnie wystartuje na porcie 3000, jeżeli chcemy korzystać ze standardowego portu 4200, możemy to zmienić dodając argument</span><span style="font-weight: 400">listen.

Po uruchomieniu wejdźmy pod adres localhost:4200/api/hello aby sprawdzić czy nasz endpoint działa.

Świetnie! Połączmy teraz naszą angularową aplikację z funkcją w nowym serwisie.

Do przetestowania serwisu stworzyłem nowy komponent, w którym wyzwalam request async pipem.

Możemy teraz sprawdzić działanie w przeglądarce!

Dynamiczne ścieżki

Wyżej opisałem działanie mapowania plików, ale nie wspomniałem o bardzo przydatnej funkcjonalności, jaką są dynamiczne ścieżki. Pliki oraz foldery, których nazwa znajduje się miedzy kwadratowymi nawiasami interpretowana jest jako ścieżka dynamiczna. Oznacza to, że przyjmie dowolny ciąg znaków.

Stworzę plik [name].ts, który będzie pobierał stringa z URL w miejscu do tego wyznaczonym:

W bibliotece express.js podobny endpoint stworzylibyśmy w ten sposób:

Możemy tworzyć ścieżki tworząc wiele dynamicznych fragmentów w drzewie plików. Nasza struktura katalogów może wyglądać przykładowo tak:

Podobnie jak w przykładzie wyżej, dynamiczne fragmenty zostaną przekazane jako query.

Cachowanie

W celu optymalizacji czasu wykonywania funkcji, możemy cachować zwracane odpowiedzi. Wymaga to ustawienia nagłówka </span><span style="font-weight: 400">Cache-Control. Vercel rekomenduje ustawienie dwóch konkretnych dyrektyw w nagłówku, tak aby kontrolować mechanizm w swojej infrastrukturze, wymuszając jednocześnie pominięcie zapamiętania odpowiedzi przez przeglądarkę. Prawidłową wartością powinno być </span><span style="font-weight: 400">max-age=0 , s-maxage=86400, gdzie </span><span style="font-weight: 400">86400 to liczba sekund warunkująca na ile odpowiedź ma zostać cache’owana. 

Dla naszej obecnej funkcji do zwracania wiadomości powitalnej, kod wyglądałby następująco:

Environment Variables

Podczas tworzenia API route’ów możemy potrzebować dodania dedykowanych zmiennych środowiskowych. Możemy je dodać w panelu lub przez komendę:

Przy dodawaniu envów możemy zaznaczyć do których środowisk klucz ma zostać zapisany. Jest to świetna opcja jeśli przykładowo posiadamy różne wersje serwisów, a klucze do nich różnią się od siebie w zależności od ich własnego środowiska.

Zmienne środowiskowe nie zostaną przekazane w procesie budowania angularowej aplikacji. Jeżeli chcielibyśmy je wykorzystać w aplikacji, możemy to zrobić przez dodatkową konfigurację webpacka, którą świetnie przedstawił nasz kolega Fanis na swoim kanale YT: https://www.youtube.com/watch?v=7ljEz52zdUM

Jeżeli zdecydowaliśmy się na dodanie envów przez panel, możemy zaciągnąć je lokalnie poprzez komendę:

Bazy Danych

Vercel niedawno dodał integracje z ich własną usługą bazy danych. Dzięki temu, możemy w łatwy sposób uzyskać do niej dostęp w naszych API route’ach. Usługa Postgres jest obecnie w fazie Beta, więc od momentu publikacji artykułu może się wiele zmienić, np. cena usługi lubi API.  

Po dodaniu bazy do naszego projektu automatycznie zostaną dodane credientale do environment variables. 

W panelu możemy użyć query console do utworzenia pierwszej tabeli. 

W ten sposób utworzyliśmy zbiornik dla naszych todos! Możemy teraz przejść do połączenia się z bazą w naszej aplikacji.  

Dodajmy endpointa w pliku </span><span style="font-weight: 400">api/todos.ts do obsługi todosów:

Nasz endpoint jest gotowy, teraz wystarczy, że obsłużymy go po stronie Angulara.

W ten sposób stworzyliśmy full-stackową todo appkę!  

Local production builds

Do tej pory używaliśmy komendy </span><span style="font-weight: 400">vercel dev w celu uruchomienia lokalnego serwera. Na pierwszy rzut oka może nas martwić brak parametrów konfiguracyjnych, domyślnie używanych przez Angular CLI, np. w komendzie </span><span style="font-weight: 400">ng serve . Powiedzmy, że chcielibyśmy mieć możliwość podglądu produkcyjnego builda. Vercel umożliwia nam stworzenie pliku konfiguracyjnego, w którym będziemy mogli nadpisywać uruchamiane komendy. 

W tym celu należy utworzyć plik </span><span style="font-weight: 400">vercel.json w głównym katalogu projektu, a następnie dodać odpowiedni wiersz z kluczem, który chcemy zmodyfikować. Uruchamianie serwera deweloperskiego to po prostu </span><span style="font-weight: 400">devCommand . Musimy dodatkowo przekazać port narzucony przez Vercel CLI.

Po ponownym uruchomieniu komendy </span><span style="font-weight: 400">vercel dev , nasz config zostanie automatycznie wykryty wraz z nadpisanymi komendami. Nie jest to jednak najlepsze wyjście, ponieważ przełączanie między konfiguracjami wymagałoby każdorazowej zmiany zawartości pliku. Lepszą opcją będzie zmiana nazwy pliku, tak aby nie był automatycznie wykrywany, przykładowo na </span><span style="font-weight: 400">vercel.prod.json . Plik ten możemy teraz przekazywać jako konfigurację przy uruchamianiu deva za pomocą argumentu </span><span style="font-weight: 400">local-config

Podsumowanie

Vercel jest świetną opcją jako platforma do deployowania Angularowych aplikacji. Dostajemy wiele przydatnych funkcjonalności i integracji, przyjazny i prosty w obsłudze panel oraz automatyzacje procesu CD. Darmowy Hobby Plan zupełnie wystarcza do side projectów. 

Poruszyliśmy jedynie kilka najważniejszych aspektów. Po pełen zakres wiedzy zachęcam do odwiedzenia dokumentacji https://vercel.com/docs

Zbudowana aplikacja jest dostępna w repozytorium na githubie pod linkiem https://github.com/Dyqmin/ng-vercel-app

 

O autorze

Dominik Donoch

Angular Developer w House of Angular. Fan IoT i automatyzacji wszelkiej formy. W wolnych chwilach podróżuję i podziwiam naturę. ExpressionChangedAfterItHasBeenCheckedError enjoyer.

Zapisz się do naszego newslettera. Bądź na bieżąco z najnowszymi trendami, poradami, meetupami i stań się częścią społeczności Angulara w Polsce. Rynek pracy docenia członków społeczności.

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *