Jak postawić Next.js na Saplo

Next.js to dziś domyślny wybór, jeśli budujesz stronę albo aplikację w Reactcie, która ma się szybko ładować i dobrze wypadać w wynikach wyszukiwania. Renderowanie po stronie serwera i App Router robią różnicę, której nie da klasyczna aplikacja SPA złożona z samego statycznego builda. Problem w tym, że taka aplikacja potrzebuje działającego procesu Node.js w tle, nie tylko katalogu z plikami HTML, więc postawienie jej na zwykłym hostingu współdzielonym zwykle się nie udaje. Na Saplo Next.js stawiasz jak każdą inną aplikację z katalogu, a Saplo od razu uruchamia go jako usługę zarządzaną z automatycznym restartem. Poniżej pokazujemy, jak to zrobić od zera, łącznie z podpięciem własnego repozytorium Git.

Dla kogo jest Next.js na Saplo

Zanim zaczniesz instalację, sprawdź, czy to dobry wybór dla Twojego projektu:

• masz albo budujesz projekt w Next.js z App Routerem - Saplo wykrywa strukturę projektu i uruchamia next start jako usługę, nie musisz sam pisać configu pm2 ani systemd,
• potrzebujesz SSR albo ISR, nie tylko statycznego builda - jeśli Twoja strona jest w pełni statyczna, tańszy i lżejszy będzie stack React albo Astro z tego samego katalogu aplikacji,
• chcesz wdrożeń z git push zamiast ręcznego przesyłania plików - podpinasz repozytorium raz, a każdy push na gałąź produkcyjną buduje i wdraża nową wersję automatycznie,
• rośnie Ci rachunek za hosting projektu, który dziś stoi na Vercelu albo Netlify - migrujesz kod jeden do jednego, next.config.* zostaje bez zmian, płacisz za Box zamiast za zużycie funkcji.

Jeśli Twój projekt to czysty frontend bez potrzeby renderowania po stronie serwera, sprawdź w katalogu aplikacji stack React albo Astro, oba są lżejsze i tańsze w utrzymaniu.

Wymagania

Żeby postawić Next.js na Saplo, potrzebujesz:

• Boxa w planie L lub wyższym - Saplo oficjalnie rekomenduje ten poziom dla Next.js, bo renderowanie po stronie serwera potrzebuje więcej zapasu RAM niż zwykła strona statyczna, niższe plany wystarczą tylko na bardzo mały ruch testowy,
• minimum 512 MB wolnego RAM i 2 GB miejsca na dysku pod sam proces aplikacji,
• domeny albo subdomeny *.saploapp.pl w cenie każdego planu, pod którą stanie aplikacja,
• repozytorium Git na GitHubie, GitLabie albo Bitbuckecie, jeśli chcesz korzystać z automatycznego wdrażania (opcjonalne na start, aplikację możesz też wgrać archiwum .zip przez panel),
• osobnej bazy danych zwykle NIE potrzebujesz, chyba że Twoja aplikacja sama się z jakąś łączy, Saplo tego za Ciebie nie narzuca.

Instalacja krok po kroku

1. W panelu Saplo wejdź w Katalog aplikacji i wybierz Next.js (kategoria "Frameworki").
2. Wskaż Box w planie L lub wyższym oraz nazwę aplikacji - z niej powstaje domyślna subdomena <nazwa>.saploapp.pl, własną domenę możesz dodać teraz albo później.
3. Zatwierdź instalację. Silnik provisionuje moduł na Boxie i uruchamia startowy szkielet Next.js (odpowiednik create-next-app), żeby od razu było co zobaczyć pod domeną, zanim wdrożysz własny kod.
4. Saplo uruchamia aplikację jako usługę zarządzaną z automatycznym restartem, a nginx na Boxie kieruje ruch z domeny na port procesu Next.js.
5. Po zakończeniu instalacji domena z kroku 2 pokazuje działającą stronę startową - od tego momentu wdrażasz na nią własny projekt.

Wdrożenie własnego kodu przez Git

1. W szczegółach aplikacji znajdź sekcję Git / CI-CD i kliknij "Połącz GitHub", potwierdź instalację aplikacji "Saplo Deploy" na swoim koncie lub organizacji i wskaż repozytorium z projektem Next.js.
2. W katalogu głównym repozytorium musi leżeć plik saplo.yaml, wygenerujesz go poleceniem saplo init albo napiszesz ręcznie (przykład niżej).
3. Zacommituj i wypchnij plik saplo.yaml na gałąź produkcyjną (domyślnie main, zmienisz ją w sekcji branches.production tego samego pliku).
4. Każdy kolejny git push na tę gałąź uruchamia automatyczny build i wdrożenie, status widzisz w panelu w zakładce Deploymenty oraz jako zielony albo czerwony znacznik przy commicie na GitHubie.
5. Jeśli build albo healthcheck się nie powiedzie, poprzednia działająca wersja aplikacji zostaje na miejscu, Saplo nie podmienia jej na zepsutą.

Przykład minimalnego pliku saplo.yaml dla Next.js:

name: moj-projekt
stack: nextjs
runtime:
  node: "22"
build:
  install: npm ci
  command: npm run build
start:
  command: npm start
  port: 3000

Wypchnięcie tego pliku wygląda tak samo jak każdy inny commit:

git add saplo.yaml
git commit -m "add saplo.yaml"
git push origin main

Next.js na Saplo kontra alternatywy

Najczęstsze pytania

Czy muszę od razu podpinać Git, czy mogę zacząć bez tego? Możesz zacząć bez Gita. Instalacja z katalogu aplikacji stawia działający szkielet Next.js, a pierwsze wdrożenie własnego kodu możesz zrobić przez upload archiwum .zip w panelu, Git podpinasz w dowolnym momencie później.

Dlaczego rekomendowany jest Box L, a nie niższy plan? Bo renderowanie po stronie serwera (SSR) trzyma proces Node.js stale w pamięci i odpowiada na każde żądanie na nowo, w odróżnieniu od strony statycznej, która raz zbudowana leży na dysku. Niższe plany wystarczą do testów, ale pod realnym ruchem produkcyjnym zabraknie im zapasu RAM.

Co się stanie, jeśli w repozytorium nie ma pliku saplo.yaml? Przy pierwszym wdrożeniu bez tego pliku deploy zakończy się błędem. Przy kolejnych, jeśli plik zniknie z konkretnego commita, Saplo użyje konfiguracji z ostatniego udanego wdrożenia.

Czy port aplikacji muszę ustawiać ręcznie? Nie musisz, domyślny port to 3000 i większość projektów Next.js nie wymaga jego zmiany. Jeśli Twoja aplikacja go zmienia, ustaw to w sekcji start.port pliku saplo.yaml.

Czy mogę mieć na jednym Boxie kilka aplikacji Next.js obok siebie? Tak, katalog aplikacji pozwala postawić wiele modułów na jednym Boxie, każdy z własną subdomeną albo domeną, dopóki starcza RAM-u i miejsca na dysku przydzielonego do planu.

Next.js na Saplo stawiasz od zera do działającej domeny w kilka minut, a każdy kolejny git push wdraża nową wersję bez Twojego udziału. Jeśli migrujesz istniejący projekt z Vercela albo Netlify i coś nie działa tak, jak powinno, napisz do nas, pomożemy dobrać konfigurację w saplo.yaml.