Full Stack FastAPI Template — FastAPI, React, PostgreSQL i Docker

Szablony projektów są najbardziej zdradliwą kategorią otwartego kodu. Nowa biblioteka od razu pokaże, że nie działa. Szablon działa zawsze — tylko że zaciąga wersje z zeszłego roku, powiela wzorce, od których autorzy frameworków już odeszli, i wpisuje ci do repozytorium decyzje, których nikt nie rewiduje od trzech lat.

Dlatego przy szablonie pierwsze pytanie nie brzmi „co jest w środku", ale „czy ktoś to jeszcze przemyślał". W tym przypadku odpowiedź jest zaskakująco dobra: projekt przeszedł w 2026 roku poważne uproszczenie, w którym usunięto z niego więcej, niż dodano.

Najpierw adres

Repozytorium się przeniosło i stary adres tylko przekierowuje. Szablon nie leży już na koncie autora FastAPI, ale na koncie organizacji: fastapi/full-stack-fastapi-template. Zmiana kosmetyczna, ale świadczy o tym, że projekt przeszedł z „prywatnego repozytorium jednej osoby" do zasobów organizacji.

Stan projektu

45 489 gwiazdek, 9055 forków, licencja MIT, historia od lutego 2019. Repozytorium jest oznaczone jako szablon, więc zakłada się w nim projekt jednym przyciskiem.

Liczba, która przekonuje mnie najbardziej: jedenaście otwartych zgłoszeń. Jedenaście, przy czterdziestu pięciu tysiącach gwiazdek. Nie widziałem w tej serii lepszego wskaźnika, że ktoś naprawdę pilnuje tego repozytorium.

Wydania też układają się w sensowny rytm: 0.12.0 z 12 sierpnia 2026, wcześniej dwa wydania z serii 0.11 w tym samym tygodniu sierpnia, a przed nimi 0.10.0 ze stycznia 2026. Sprawdziłem historię commitów pod kątem tego, czy to nie tylko podbijanie zależności — nie jest: w ostatnich miesiącach doszły szablony wiadomości pocztowych, testy końcowe logowania i rejestracji, uproszczenie sprawdzania gotowości bazy i poprawki motywu powiadomień. To praca merytoryczna, nie kosmetyka.

Co jest w środku

Stos jest nowoczesny i — co ważniejsze — spójny:

Zaplecze: FastAPI, SQLModel jako warstwa dostępu do bazy, Pydantic do walidacji i konfiguracji, PostgreSQL.
Front: React z TypeScriptem, Vite, Tailwind CSS i shadcn/ui jako biblioteka komponentów, obsługa trybu ciemnego.
Klient API generowany automatycznie ze schematu — czyli funkcje wywołujące zaplecze nie są pisane ręcznie i nie rozjadą się z serwerem.
Testy: Pytest na zapleczu, Playwright do testów końcowych w przeglądarce.
Uwierzytelnianie: tokeny JWT, bezpieczne haszowanie haseł, odzyskiwanie hasła pocztą.
Wdrożenie: Docker Compose z Traefikiem jako odwrotnym proxy i automatycznym HTTPS, a także osobna ścieżka do chmury.
CI i CD oparte o GitHub Actions.

Warto zwrócić uwagę na wybór komponentów. Wcześniejsze wersje szablonu opierały front na innej bibliotece; dziś jest to Tailwind z shadcn/ui, czyli podejście, w którym komponenty kopiuje się do projektu, zamiast instalować jako zależność. Dla zespołu oznacza to pełną kontrolę nad kodem komponentów i brak walki z cudzymi stylami — i jest to dziś w świecie Reacta wybór głównego nurtu.

Decyzja architektoniczna, która upraszcza wszystko

Jest w tym szablonie jedno rozwiązanie, które zmienia więcej niż cała reszta listy, a łatwo je przeoczyć, bo w pliku README zajmuje pół linijki.

Front jest wbudowany w aplikację zaplecza i podawany przez FastAPI z tej samej domeny co API.

Kto stawiał aplikację rozdzieloną na dwie domeny, wie, ile kosztuje ta wygoda. Konfiguracja polityki współdzielenia zasobów, zapytania wstępne, ciasteczka między domenami, osobny certyfikat, osobne wdrożenie i osobne miejsce, w którym da się to zepsuć. Podanie frontu z tej samej domeny likwiduje całą tę kategorię problemów za jednym razem — i nieprzypadkowo jednym z commitów tego roku było uproszczenie konfiguracji współdzielenia zasobów. Nie ma czego konfigurować, gdy nie ma dwóch domen.

To nie jest rozwiązanie do każdego zastosowania: jeśli planujesz aplikację mobilną korzystającą z tego samego API albo front na sieci dostawczej, wrócisz do rozdzielenia. Ale dla narzędzia wewnętrznego, panelu administracyjnego albo pierwszej wersji produktu jest to wybór, który oszczędza kilka dni pracy i cały jeden obszar błędów.

Wydanie, które usunęło więcej, niż dodało

Seria 0.11 z sierpnia 2026 jest w historii tego szablonu punktem zwrotnym i warto wiedzieć, co dokładnie się zmieniło — zwłaszcza jeśli używałeś go wcześniej.

Usunięto generowanie projektu przez Copiera. Szablon nie jest już rozwijany jako projekt do wygenerowania narzędziem zewnętrznym, ale jako zwykły szablon repozytorium — zakłada się go przyciskiem na GitHubie i dalej edytuje po swojemu. Dla nowych osób jest to uproszczenie, dla starych zmiana procedury.

Klucz podpisujący tokeny musi być podany jawnie. Wcześniej istniała wartość domyślna, więc dało się uruchomić projekt bez zastanowienia — a potem wdrożyć go z tą wartością na produkcję. Teraz aplikacja bez tego ustawienia nie wystartuje. To jedna z tych zmian, które irytują przy pierwszym uruchomieniu i ratują skórę przy pierwszym audycie.

Przygotowanie bazy jest teraz jawnym krokiem przed startem, a nie osobnym mechanizmem uruchamianym wcześniej. Do tego doszło uproszczenie konfiguracji opcjonalnych zmiennych środowiskowych, przestawienie trybu rozwojowego na jedną zmienną i przejście na oficjalny punkt wejścia FastAPI zamiast ręcznego wywoływania serwera — również w plikach Compose.

Kierunek tych zmian czytam jako świadome przycinanie. Szablon, który przez lata narastał, został w jednym wydaniu odchudzony — a to przy szablonach rzadkość, bo zwykle rosną, aż nikt nie wie, co usunąć.

Czy szablon sam się sprawdza

Wracam na moment do pytania z początku: skąd wiadomo, że szablon nie zgnił? Otóż w tym przypadku odpowiedź jest zautomatyzowana, i to jest argument mocniejszy od dowolnej liczby gwiazdek.

Repozytorium ma dwa przepływy CI sprawdzające sam szablon: jeden uruchamia testy zaplecza, drugi podnosi cały stos przez Docker Compose. Ten drugi jest tu kluczowy — pilnuje, że polecenie, którym zaczniesz pracę, faktycznie stawia działającą aplikację. Zgnicie szablonu zwykle objawia się dokładnie w tym miejscu: pliki są, wersje nie pasują i nic się nie uruchamia. Tutaj złamanie tego wykryje maszyna, nie ty.

Warstwa narzędziowa jest przy tym współczesna po obu stronach. Zależności Pythona prowadzone są przez uv, w układzie przestrzeni roboczej — czyli najszybszym dziś menedżerem w tym ekosystemie, z blokadą wersji w repozytorium. Front ma własny plik blokady, a w katalogu głównym leży konfiguracja haków uruchamianych przed commitem, więc formatowanie i podstawowa kontrola jakości działają od pierwszego dnia, bez ustawiania.

Konfiguracja przewiduje też podłączenie zewnętrznego zbierania błędów jednym adresem — opcjonalnie, ale miejsce jest przygotowane. To znowu ta kategoria rzeczy, których nikt nie robi na starcie, a które potem dorabia się po pierwszej awarii, o której dowiedział się klient, a nie zespół.

Umiejętności dla agentów w repozytorium

A teraz rzecz, która wyróżnia ten szablon na tle wszystkiego, co widziałem w tej kategorii, i jest bardzo znakiem 2026 roku.

W repozytorium leżą dwa katalogi z umiejętnościami dla agentów AI: jeden w konwencji narzędzia Claude Code, drugi w konwencji neutralnej wobec dostawcy. Każdy zawiera dwie pozycje — dla FastAPI i dla SQLModela. Zajrzałem głębiej: nie są to dwie kopie, ale dowiązania symboliczne do wspólnego katalogu z jednym plikiem opisu umiejętności. Jedna treść, dwie konwencje, zero duplikacji.

Znaczenie praktyczne jest konkretne. Gdy asystent AI pracuje w takim repozytorium, nie musi zgadywać, jak w tym projekcie definiuje się model, gdzie kończy się schemat Pydantica, a zaczyna tabela SQLModela, ani jakich konwencji trzyma się autor frameworka. Dostaje to napisane, w miejscu, którego szuka z automatu.

Uważam, że jest to wzorzec wart skopiowania niezależnie od tego, czy użyjesz tego szablonu. Jeśli w twoim zespole asystenci AI piszą kod — a piszą — to opisanie im konwencji projektu w pliku, który sam znajdą, jest dziś tańsze niż poprawianie tego samego błędu po dziesiąty raz w przeglądzie kodu.

Poczta potraktowana poważnie

Ostatni element, na który zwróciłem uwagę, bo w szablonach bywa potraktowany po łebkach albo pominięty, a w praktyce zjada nieproporcjonalnie dużo czasu.

Szablon ma szablony wiadomości pocztowych zbudowane w React Email — czyli pisane jako komponenty Reacta, a nie jako sklejany ręcznie HTML z tabelami. Kto walczył kiedyś z wyglądem wiadomości w kilku klientach poczty, doceni to natychmiast.

Do tego w środowisku rozwojowym stoi Mailpit — lokalny serwer przechwytujący wysyłaną pocztę i pokazujący ją w przeglądarce. Dzięki temu odzyskiwanie hasła da się przetestować od początku do końca, bez konfigurowania prawdziwego dostawcy i bez ryzyka, że testowa wiadomość poleci do prawdziwego klienta. To dwie rzeczy, których nikt nie dodaje na początku projektu, a które potem trzeba dorobić w pośpiechu.

Dwie ścieżki wdrożenia i jedna uwaga

Wdrożenie jest opisane w dwóch osobnych dokumentach i warto wiedzieć, czym się różnią.

Ścieżka pierwsza to FastAPI Cloud — komercyjna usługa hostingowa, wraz z gotowym przepływem wdrożeniowym w GitHub Actions i integracjami podłączającymi bazę PostgreSQL od dwóch popularnych dostawców, które same ustawiają adres połączenia. Dokument wymienia dokładnie, co trzeba podać: nazwę projektu, adres pierwszego administratora i publiczny adres aplikacji jako zmienne, a klucz podpisujący, hasło administratora i adres bazy jako sekrety. Jest nawet gotowe polecenie generujące bezpieczne wartości losowe.

Ścieżka druga to Docker Compose z Traefikiem i automatycznym HTTPS — czyli wdrożenie na własnym serwerze, opisane w osobnym dokumencie równie dokładnie.

I tu uwaga, którą uważam za potrzebną: domyślną, pierwszą udokumentowaną ścieżką jest usługa komercyjna powiązana z twórcą frameworka. Nie ma w tym niczego nieuczciwego — obsługa chmury doszła jako funkcja wydania 0.12.0, kod pozostaje na licencji MIT, a wdrożenie na własnym serwerze jest opisane równolegle i pełnoprawnie. Warto natomiast mieć to z tyłu głowy przy planowaniu dłuższym: warto obserwować, czy w kolejnych wydaniach ścieżka samodzielna pozostanie równie dopieszczona.

Dla polskiej firmy ta druga ścieżka ma zresztą konkretną wartość. Aplikacja przetwarzająca dane osobowe klientów, postawiona na własnym serwerze w Unii, oszczędza cały rozdział rozważań o przekazywaniu danych do państw trzecich. Szablon daje tu gotowy zestaw — proxy, certyfikaty, orkiestracja — a nie tylko odesłanie do cudzej chmury.

Pułapki w jednym miejscu

Repozytorium się przeniosło na konto organizacji; stary adres przekierowuje, ale zakładki i skrypty warto poprawić.
Generowanie przez Copiera zostało usunięte w serii 0.11. Jeśli miałeś na tym procedurę, trzeba ją zmienić na zakładanie z szablonu repozytorium.
Klucz podpisujący tokeny trzeba podać jawnie — bez niego aplikacja nie wystartuje. To zmiana zamierzona.
Front podawany z tej samej domeny upraszcza wdrożenie, ale wymaga przemyślenia, jeśli planujesz aplikację mobilną albo osobny front na sieci dostawczej.
Numeracja wersji poniżej jedynki. Szablon jest dojrzały, ale sam wciąż deklaruje wersje z serii zerowej — zmiany łamiące zgodność bywają, jak pokazała seria 0.11.
Szablon to punkt startu, nie zależność. Po założeniu projektu jego przyszłe poprawki nie dopłyną do ciebie same; aktualizacje trzeba przenosić ręcznie.
Pierwsza ścieżka wdrożenia prowadzi do usługi komercyjnej. Samodzielna jest udokumentowana, ale to ty musisz ją wybrać świadomie.
Sekrety w konfiguracji chmurowej trzeba oznaczyć jako sekrety — dokumentacja wylicza, które i dlaczego. Warto tę listę przejść bez skrótów.

Podsumowanie

To jest szablon, po który sięgnąłbym bez wahania przy narzędziu wewnętrznym, panelu administracyjnym albo pierwszej wersji produktu w Pythonie. Nie dlatego, że ma najdłuższą listę funkcji, ale dlatego, że ktoś w tym roku usiadł i część z nich usunął.

Jedenaście otwartych zgłoszeń przy czterdziestu pięciu tysiącach gwiazdek.
Front podawany przez zaplecze z jednej domeny — cała kategoria problemów z konfiguracją znika.
Klient API generowany ze schematu, więc front nie rozjedzie się z serwerem.
Poczta jako pełnoprawny element — szablony w React Email i lokalny przechwytywacz do testów.
Umiejętności dla agentów AI w repozytorium, w dwóch konwencjach, bez duplikowania treści.
Dwie równolegle udokumentowane ścieżki wdrożenia — chmura komercyjna i własny serwer z automatycznym HTTPS.
Bezpieczne wartości domyślne wymuszone siłą — brak klucza oznacza brak startu.

Licencja to MIT i przy szablonie projektu jest to dokładnie ta licencja, której się chce. Zakładasz z niego własne repozytorium, przepisujesz połowę, sprzedajesz produkt i nie masz wobec nikogo obowiązków poza zachowaniem informacji o prawach autorskich w plikach, które przejąłeś. Żadnego zarażania licencją, żadnego obowiązku otwierania własnego kodu, żadnych ograniczeń komercyjnych.

MIT nie daje natomiast gwarancji ani wsparcia — ale przy szablonie ma to inne znaczenie niż przy bibliotece. Szablonu nie aktualizujesz: od momentu założenia projektu ten kod jest twój, wraz z odpowiedzialnością za jego utrzymanie. To zresztą największa różnica praktyczna, o której warto pamiętać przy podejmowaniu decyzji. Biblioteka rozwija się razem z tobą; szablon daje ci dobry start i zostawia cię z nim. Im lepiej przemyślany start, tym mniej to boli — a ten jest przemyślany naprawdę dobrze.