Co dostarczyliśmy
Open Circle rozwija Valibot i Formisch, dwie biblioteki TypeScript, których dokumentacja jest dla reszty ekosystemu materiałem źródłowym. Oba serwisy mają rozbudowaną część referencyjną i oba renderowały każdą podstronę przy wejściu, na Vercel Edge. Przebudowaliśmy je tak, żeby każda podstrona powstawała raz, podczas kompilacji, i była serwowana jako gotowy plik.
Całość zmieściła się w dwóch pull requestach rozłożonych na kilka weekendów. To pierwsze wdrożenie w ramach naszego OSS Partner Program.
Zakres prac
Obie dokumentacje przeszły z renderowania przy wejściu na w pełni statyczną kompilację, razem z każdą podstroną części referencyjnej.
Ustawienia czytelnika, czyli motyw, kolumna z rozdziałami i wybór frameworka, wyprowadzone z ciasteczek odczytywanych na serwerze do przeglądarki i wczytywane, zanim strona zostanie narysowana.
Obrazy podglądu do social mediów generowane raz na trasę, podczas kompilacji, zamiast rysowane przy każdym zapytaniu bota.
Nagłówki cache ustawione osobno dla każdej klasy plików, tak żeby zasoby z hashem w nazwie mogły leżeć rok, a dane nawigacji pozostawały aktualne po każdym wdrożeniu.
Patch do statycznej kompilacji w Qwik Routerze, która gubiła podstrony o adresach zakończonych rozszerzeniem pliku.
Co się zmieniło dla czytelnika
Nic, co dałoby się wskazać palcem, i o to chodziło. Nawigacja nadal zachowuje się jak aplikacja, motyw i układ nadal przeżywają odświeżenie, podstrony wyglądają tak samo. Różnica siedzi pod spodem: podstrona wraca z cache, zamiast powstawać pod konkretne wejście, żadne wejście nie budzi funkcji, a odtworzenie zapisanego ustawienia nie rusza już strony po tym, jak zostanie narysowana.
Co się zmieniło dla zespołu
Z kompilacji wychodzi zwykły HTML, JSON, fonty i obrazy, bez niczego przywiązanego do jednego adaptera hostingowego. Hosting znowu jest decyzją, którą można podjąć od nowa w dowolnym momencie, a nie zależnością, w której się siedzi. Dziś oba serwisy stoją na Cloudflare.
Dla zespołu biblioteki znaczenie ma jeszcze jedno: koszt utrzymania dokumentacji przestał rosnąć razem z liczbą osób, które ją czytają. Ruch na części referencyjnej to dokładnie ten ruch, na którym takiemu projektowi zależy, i nie powinien być pozycją, którą trzeba pilnować.
Dlaczego się tego podjęliśmy
OSS Partner Program powstał po to, żeby zdejmować z zespołów open source powtarzalną robotę wokół infrastruktury i utrzymania, a ich czas i pieniądze zostawiać przy bibliotekach, na których stoi reszta ekosystemu. Hosting dokumentacji jest tu dobrym przykładem: nigdy nie przestaje wymagać uwagi i nigdy nie jest powodem, dla którego ktokolwiek dołączył do projektu.
Szczegóły techniczne
Najciekawsze fragmenty nie mieszczą się w podsumowaniu: jak wczytać ustawienia czytelnika, zanim przeglądarka cokolwiek narysuje, dlaczego danych nawigacji nie wolno oznaczyć jako immutable i co po cichu wypadało z kompilacji. Opisaliśmy to osobno w tekście Dokumentacja z cache zamiast z serwera.
