Wstęp#

Często skupiamy się na optymalizacji JavaScriptu czy obrazów, a style CSS traktujemy nieco po macoszemu. Wydaje nam się, że skoro pojedyncze pliki ważą zaledwie kilka kilobajtów, to nie stanowią problemu. Jednak to mylne założenie. Sposób, w jaki dostarczamy te pliki do przeglądarki, może mieć kluczowy wpływ na to, jak szybko użytkownik zobaczy gotową stronę.

Kiedy zajrzałem do narzędzi deweloperskich w Chrome, zauważyłem u siebie konkretny problem. Moja strona ładowała aż piętnaście osobnych plików CSS. Sumarycznie generowało to opóźnienie rzędu jednej i sześciu dziesiątych sekundy. Co ciekawe, problemem wcale nie był rozmiar danych. Kompresja GZIP działała poprawnie i redukowała wagę plików o ponad sześćdziesiąt procent. Prawdziwym wąskim gardłem okazała się sama liczba zapytań HTTP. Przeglądarka traciła czas na nawiązywanie połączeń, zamiast na pobieranie treści.

W tym wpisie pokażę Wam, jak rozwiązać ten problem w Hugo, przechodząc przez trzy etapy optymalizacji.

Po pierwsze, zajmiemy się zaawansowaną konfiguracją minifikacji, co pozwoli nam zaoszczędzić dodatkowe bajty. Po drugie, wdrożymy CSS bundling. Zamiast kilkunastu plików, będziemy serwować jeden, co drastycznie zmniejszy narzut sieciowy. Na koniec omówimy fingerprinting, czyli mechanizm pozwalający na bezpieczne i długoterminowe cache’owanie zasobów w przeglądarce.

Problem: Analiza CSS przed optymalizacją#

Aby zrozumieć skalę problemu, zajrzałem w głąb pliku HAR wygenerowanego przez Chrome DevTools. Liczby od razu rzuciły się w oczy. Na stronie głównej przeglądarka wykonywała łącznie trzydzieści cztery zapytania HTTP. Co istotne, aż piętnaście z nich dotyczyło samych arkuszy stylów. Większość pochodziła z motywu strony, a jeden był zewnętrznym zasobem z Google Fonts.

Mimo że pliki te były niezwykle lekkie — łącznie ważyły zaledwie jedenaście kilobajtów po kompresji GZIP — ich pobranie trwało stanowczo zbyt długo. Średni czas dla pojedynczego pliku wynosił ponad sto milisekund, co sumarycznie dawało wynik w okolicach jednej i sześciu dziesiątych sekundy.

Gdy przyjrzałem się szczegółowej liście plików, takich jak buttons.css, header.css czy menu.css, zauważyłem powtarzalny wzorzec. Niezależnie od tego, czy plik ważył dwa kilobajty, czy tylko pięćset bajtów, narzut czasowy był niemal identyczny. To jasno wskazało na trzy kluczowe problemy architektury.

Po pierwsze, nadmiarowa liczba zapytań. Każde z piętnastu zapytań niesie ze sobą koszt nawiązania połączenia, przesłania nagłówków i tak zwanego “TCP slow-start”. Warto pamiętać, że choć protokół HTTP/2 oferuje multipleksowanie, co teoretycznie pomaga w takich sytuacjach, narzut nadal pozostaje znaczący. W moim przypadku te drobne opóźnienia skumulowały się do ponad półtorej sekundy.

Po drugie, brak strategii cache’owania. Zauważyłem, że serwer nie wysyłał odpowiednich nagłówków cache, a pliki nie posiadały unikalnych sygnatur, czyli fingerprintingu. Oznacza to, że przy każdej wizycie przeglądarka musiała pobierać te same style od nowa, zamiast sięgnąć do pamięci podręcznej.

Trzecim punktem była zachowawcza minifikacja. Hugo w domyślnej konfiguracji minifikuje pliki w sposób bezpieczny, ale nie optymalny. Zauważyłem tu potencjał na “urwanie” dodatkowych kilkunastu procent z rozmiaru plików poprzez bardziej zaawansowane ustawienia.

Diagnoza była więc prosta: wąskim gardłem nie była przepustowość łącza, ale sama mechanika przesyłania danych. Mieliśmy piętnaście małych plików, które blokowały renderowanie strony przez ponad półtorej sekundy.

Poziom 1: Zaawansowana konfiguracja minify#

Pierwszym krokiem, który podjąłem, było przyjrzenie się, jak Hugo radzi sobie z minifikacją plików. Standardowo, gdy używamy flagi do minifikacji, Hugo stosuje dość zachowawczą konfigurację. Działa to bezpiecznie, ale zostawia sporo miejsca na poprawę. Postanowiłem więc nadpisać domyślne ustawienia, aby wycisnąć z nich maksimum wydajności.

Zmiany zaczynamy od głównego pliku konfiguracyjnego. Poniższy fragment definiuje bardziej agresywne reguły kompresji dla różnych typów plików.

Konfiguracja hugo.toml#

# Minification settings for optimal performance
[minify]
  minifyOutput = true

  [minify.tdewolff]
    [minify.tdewolff.html]
      keepComments = false
      keepWhitespace = false
      keepEndTags = true
      keepQuotes = false
      keepDefaultAttrVals = true
      keepDocumentTags = true

    [minify.tdewolff.css]
      precision = 2

    [minify.tdewolff.js]
      keepVarNames = false
      precision = 2
      version = 2022

    [minify.tdewolff.json]
      precision = 2

    [minify.tdewolff.svg]
      keepComments = false
      precision = 0

    [minify.tdewolff.xml]
      keepWhitespace = false

Co nam dają te ustawienia?#

Pozwólcie, że wyjaśnię logikę stojącą za tymi zmianami, bo diabeł tkwi w szczegółach.

W przypadku HTML-a, zdecydowałem się na całkowite usunięcie komentarzy i zbędnych białych znaków. Co ciekawe, wyłączamy też zachowywanie cudzysłowów tam, gdzie to możliwe. Przeglądarki świetnie radzą sobie z interpretacją atrybutów bez nich, a my oszczędzamy cenne bajty.

Jeśli chodzi o CSS i JavaScript, kluczowa jest precyzja liczb. Zamiast domyślnych, długich rozwinięć dziesiętnych, zaokrąglamy wartości do dwóch miejsc po przecinku. Dla ludzkiego oka na ekranie różnica jest niezauważalna, ale dla rozmiaru pliku ma to spore znaczenie. Dodatkowo w JavaScript pozwalamy na skracanie nazw zmiennych.

Mały wyjątek zrobiłem dla SVG. Tutaj ustawienie precyzji na zero oznacza w kontekście Hugo brak zaokrąglania. Zależy nam na zachowaniu pełnej precyzji wektorów, aby grafiki nie traciły na jakości.

Optymalizacja procesu buildowania#

Warto też włączyć generowanie statystyk budowania. To drobna zmiana w konfiguracji, ale bardzo przydatna, gdy później chcemy audytować, co dokładnie wpadło do naszej paczki.

[build]
  writeStats = true

Flagi w procesie deploymentu#

Sama konfiguracja to połowa sukcesu. Druga to sposób, w jaki uruchamiamy nasz build. W moim pipeline produkcyjnym używam zestawu dwóch flag.

hugo --minify --gc

Flaga –minify aktywuje te agresywne ustawienia, które zdefiniowaliśmy wcześniej. Z moich obserwacji wynika, że dla typowego bloga redukuje to rozmiar kodu HTML i CSS o kolejne dwadzieścia do trzydziestu procent.

Druga flaga, –gc czyli Garbage Collection, dba o higienę naszego projektu. Czyści ona katalog zasobów z nieużywanych plików, które mogły zostać z poprzednich wersji. Jest to szczególnie ważne w procesach CI/CD, bo gwarantuje nam spójność środowiska i zapobiega “puchnięciu” folderów cache.

Efekt tych zmian był natychmiastowy. Rozmiar samego HTML-a spadł u mnie z około dziesięciu do ośmiu kilobajtów, a CSS stał się znacznie lżejszy.

Poziom 2: CSS Bundling#

To, co wcześniej zidentyfikowaliśmy jako główny problem – czyli fragmentacja plików CSS – wymaga teraz radykalnego rozwiązania. Wiele motywów, w tym popularny Terminal, domyślnie ładuje każdy moduł stylów (przyciski, kod, czcionki) jako osobny zasób. Wygląda to mniej więcej tak:

<link rel="stylesheet" href="/css/buttons.min.abc123.css">
<link rel="stylesheet" href="/css/code.min.def456.css">
<link rel="stylesheet" href="/css/fonts.min.ghi789.css">
<!-- ... 12 więcej plików = 15 total -->

Jak już ustaliliśmy, mimo dobrodziejstw protokołu HTTP/2, każde z tych zapytań generuje narzut. Moje dane były bezlitosne: piętnaście małych plików “kosztowało” przeglądarkę ponad półtorej sekundy. Czas to zmienić.

Rozwiązanie: Hugo Pipes bundling#

Hugo posiada wbudowany, potężny mechanizm zwany Hugo Pipes. Pozwala on na przetwarzanie zasobów w locie. Naszym celem jest zebranie tych wszystkich luźnych plików i sklejenie ich w jedną, zoptymalizowaną paczkę (bundle).

Co ważne, nie będziemy edytować plików źródłowych motywu – to zła praktyka, która utrudnia późniejsze aktualizacje. Zamiast tego, nadpiszemy jedynie plik odpowiedzialny za nagłówek strony.

Implementacja krok po kroku#

Zacznijmy od skopiowania pliku head.html z motywu do naszego katalogu projektu, aby móc go bezpiecznie edytować.

Następnie otwieramy ten plik i podmieniamy sekcję ładującą style. Zamiast pętli generującej dziesiątki linków, wstawiamy poniższą logikę.

{{ $css := resources.Match "css/*.css" }}
{{ $bundledCSS := $css | resources.Concat "css/bundle.css" | minify | fingerprint }}

{{/* Preload for faster initial render */}}
<link rel="preload" href="{{ $bundledCSS.Permalink }}" as="style">
<link rel="stylesheet" href="{{ $bundledCSS.Permalink }}">

Warto rozważyć też wariant hybrydowy. Często chcemy, aby style motywu (które rzadko się zmieniają) były w jednej paczce, a nasze własne poprawki w osobnej. To ułatwia development, choć dodaje jedno zapytanie więcej. Decyzja należy do Ciebie, ale oto jak to zrobić:

{{/* Bundle theme CSS */}}
{{ $themeCss := resources.Match "css/*.css" | resources.Concat "css/bundle.css" | minify | fingerprint }}
<link rel="preload" href="{{ $themeCss.Permalink }}" as="style">
<link rel="stylesheet" href="{{ $themeCss.Permalink }}">

{{/* Your custom CSS (easier to edit separately) */}}
{{ $customCss := resources.Get "style.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $customCss.Permalink }}">

Co dokładnie dzieje się “pod maską”?#

Ten krótki fragment kodu wykonuje ogromną pracę, którą warto zrozumieć. Najpierw resources.Match skanuje katalog zasobów i wyłapuje wszystkie pliki z rozszerzeniem .css. Funkcja Concat łączy je w jeden fizyczny plik bundle.css, dbając o zachowanie kolejności (co jest kluczowe dla kaskadowości stylów). Następnie wchodzi minify, tutaj aplikowane są te agresywne reguły kompresji, które ustawiliśmy w pierwszym kroku. Kluczowym elementem jest fingerprint. Dodaje on unikalny skrót (hash) zawartości do nazwy pliku. To nasza polisa ubezpieczeniowa przeciwko problemom z cachem. Na koniec używamy preload, dając przeglądarce sygnał: “hej, ten plik jest krytyczny, pobierz go w pierwszej kolejności”. To bezpośrednio przekłada się na szybsze pojawienie się treści na ekranie (FCP).

Fingerprinting i magia cache’owania#

Dzięki funkcji fingerprint, finalna nazwa naszego pliku wygląda mniej więcej tak:

bundle.min.b8ee5840c5ea050eecdf3b702643ce8213a5b7388d2aa71f87c043d4a1474c4e.css

Mechanizm jest genialny w swojej prostocie. Dopóki nie zmienisz ani przecinka w stylach, nazwa pliku (a więc i hash) pozostaje taka sama, a przeglądarka korzysta z wersji zapisanej w pamięci podręcznej. Wystarczy jednak, że zmienisz kolor jednego przycisku, a Hugo wygeneruje nowy hash.

Efekt? Nowa nazwa pliku wymusza na przeglądarce pobranie świeżej wersji, podczas gdy stara wersja po prostu przestaje być używana. Możemy więc bez obaw ustawić bardzo długi czas wygasania cache’u (nawet rok!), mając pewność, że użytkownicy zawsze zobaczą aktualną wersję strony.

Weryfikacja#

Na koniec, jak każdy dobry inżynier, musimy sprawdzić, czy to faktycznie działa. Uruchamiamy build i sprawdzamy wynik.

hugo --minify --gc

# Check size of bundle CSS
ls -lh public/css/bundle*.css

# Check HTML how many css links contain
grep -o '<link[^>]*css[^>]*>' public/index.html

Jeśli po grepnięciu pliku HTML widzisz tylko jeden link do CSS zamiast kilku/kilkunastu to gratulacje. Właśnie odchudziłeś swoją stronę o zbędne zapytania.

Wyniki optymalizacji CSS#

Pora powiedzieć “sprawdzam”. Wróciłem do Chrome DevTools, wyczyściłem cache przeglądarki i uruchomiłem profilowanie ponownie. Różnica w odczuwalnej prędkości ładowania była widoczna gołym okiem, ale to twarde dane zrobiły na mnie największe wrażenie.

Zestawmy ze sobą sytuację przed i po zmianach:

Stan przed optymalizacją (Baseline)#

Łączna liczba requestów HTTP: 34
Pliki CSS: 15
CSS rozmiar (uncompressed): 29 KB
CSS rozmiar (GZIP): 11 KB
Łączny czas CSS: 1,635ms
Cache headers: Brak

Stan po wdrożeniu zmian (Bundle + Minify)#

Pliki CSS: 3 (bundle.css + style.css + Google Fonts) (↓ 80%)
CSS rozmiar (uncompressed): 29 KB (bez zmian)
Bundle główny: 19.7 KB (uncompressed), czas: 58ms
style.css: 7.2 KB, czas: 51ms
Google Fonts: 2.5 KB, czas: 26ms
Łączny czas CSS: 135ms (↓ 92%! ⚡)
Cache headers: public, max-age=31536000, immutable

Analiza kluczowych metryk#

Kiedy patrzę na te liczby, nasuwają mi się trzy główne wnioski, które warto zapamiętać przy optymalizacji dowolnego projektu webowego.

  1. Czas to nie tylko rozmiar pliku

To najważniejsza lekcja z tego eksperymentu. Zauważcie, że sumaryczny rozmiar kodu CSS (29 KB) pozostał praktycznie bez zmian. Mimo to, czas ładowania spadł z 1,6 sekundy do zaledwie 135 milisekund. To redukcja o 92%. Udowodniliśmy tym samym, że wąskim gardłem nie była przepustowość łącza, ale narzut związany z obsługą wielu połączeń.

  1. Mniej znaczy szybciej (Redukcja requestów)

Zredukowaliśmy liczbę zapytań o pliki stylów o 80% (z 15 do 3). Ten zabieg “odciążył” całą stronę, zwalniając miejsce w kolejce requestów. Dzięki temu przeglądarka może szybciej zająć się pobieraniem innych zasobów, np. obrazków czy skryptów JS, zamiast tracić czas na “żonglowanie” małymi plikami CSS.

  1. Stabilność dzięki Cache Headers

Ostatni, ale równie ważny punkt to nagłówki. Wcześniej ich brakowało. Teraz, dzięki max-age=31536000 i immutable, przeglądarka wie, że może bezpiecznie trzymać te pliki przez rok. Użytkownik, który wróci na moją stronę jutro, za tydzień czy za miesiąc, nie pobierze ani bajta stylów CSS – zostaną one załadowane błyskawicznie z dysku.

Podsumowując: przy minimalnym nakładzie pracy konfiguracyjnej w Hugo, udało nam się wyeliminować jeden z największych spowalniaczy strony. To przykład optymalizacji, która ma bardzo wysoki współczynnik zwrotu z inwestycji czasu (ROI).

Pułapki, na które warto uważać#

Wdrożenie bundlingu brzmi świetnie na papierze, ale w praktyce możecie natrafić na kilka “raf”, które sam musiałem ominąć. Oto dwa najczęstsze problemy i sprawdzone sposoby na radzenie sobie z nimi.

Problem 1: CSS w losowej kolejności (rozjechane style)#

Może się zdarzyć, że po złączeniu plików Wasza strona będzie wyglądać dziwnie. Przyciski stracą kolory, a układ się posypie. Dlaczego? Pamiętajcie, że w CSS kolejność ma znaczenie (w końcu to Cascading Style Sheets).

Kiedy używamy funkcji resources.Match, Hugo pobiera pliki pasujące do wzorca, ale niekoniecznie w tej kolejności, na której nam zależy (często alfabetycznie). Jeśli plik z nadpisaniami (overrides.css) załaduje się przed plikiem bazowym, style nie zadziałają.

Rozwiązanie#

Jeśli kolejność jest kluczowa, zrezygnujcie z automatycznego dopasowywania (Match). Zamiast tego, zdefiniujcie kolejkę ręcznie, tworząc tzw. slice. To daje 100% pewności, że normalize.css będzie zawsze pierwszy, a utilities.css ostatni.

{{ $cssFiles := slice
  (resources.Get "css/normalize.css")
  (resources.Get "css/base.css")
  (resources.Get "css/components.css")
  (resources.Get "css/utilities.css")
}}
{{ $bundledCSS := $cssFiles | resources.Concat "css/bundle.css" | minify | fingerprint }}

Problem 2: Google Fonts poza paczką#

Podczas weryfikacji bundle’a możecie zauważyć, że brakuje w nim stylów czcionek. Dzieje się tak, jeśli korzystacie z zewnętrznych źródeł, takich jak Google Fonts.

Mechanizm Hugo Pipes operuje wyłącznie na plikach lokalnych, znajdujących się w katalogu assets. Hugo nie pobiera automatycznie zawartości z zewnętrznych serwerów (jak fonts.googleapis.com) podczas budowania paczki, przez co linki zewnętrzne są ignorowane przez proces resources.Concat.

Rozwiązanie#

Macie dwie drogi. Możecie pobrać pliki czcionek na dysk i serwować je lokalnie (co jest świetne dla prywatności i RODO), albo prostsze zostawić je jako osobne zapytanie. W tym drugim przypadku, po prostu oddzielamy logikę dla lokalnego CSS i zewnętrznych fontów.

<!-- Bundle internal CSS -->
{{ $bundledCSS := ... }}

<!-- External fonts separately -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fira+Code&display=swap">

Podsumowanie#

Optymalizacja CSS w Hugo to klasyczny przykład zasady Pareto – relatywnie mały nakład pracy przyniósł nieproporcjonalnie duże korzyści. Spójrzmy na twarde dane z produkcji: liczbę zapytań o style zredukowaliśmy o 80% (z 15 do 3), a czas ich ładowania skrócił się o 92% – z 1.6 sekundy do zaledwie 0.14 sekundy.

Dlaczego to zadziałało? Sukces tej optymalizacji opiera się na kilku solidnych filarach inżynierskich:

  1. Redukcja narzutu HTTP – Mniej zapytań oznacza mniej czasu traconego na handshake’i TCP i przesyłanie nagłówków.

  2. Efektywna minifikacja – Agresywna konfiguracja pozwoliła usunąć każdy zbędny bajt.

  3. Fingerprinting i Cache – Dzięki hashowaniu plików mogliśmy bezpiecznie wdrożyć politykę immutable cache. Przeglądarka wie teraz, że zasób się nie zmienił, więc nawet nie pyta serwera o aktualizację.

  4. Preloading – Jawne wskazanie priorytetu ładowania poprawiło wskaźnik First Contentful Paint.

Wartość długoterminowa#

Co te zmiany oznaczają w praktyce dla użytkowników?

Dla nowych odwiedzających, strona ładuje się odczuwalnie płynniej, szczególnie na urządzeniach mobilnych, gdzie każde dodatkowe połączenie na słabym zasięgu jest kosztowne.

Jednak prawdziwą magię widzą powracający użytkownicy. Dzięki poprawnym nagłówkom cache (max-age=31536000), style są ładowane bezpośrednio z dysku urządzenia w czasie 0 ms. Po pierwszej wizycie sieć przestaje być wąskim gardłem dla warstwy wizualnej.

Mówiąc krótko: CSS bundling w Hugo to typowe “low hanging fruit”. To optymalizacja łatwa do wdrożenia, bezpieczna w utrzymaniu i dająca natychmiastowy, mierzalny skok wydajności. Jeśli jeszcze tego nie zrobiliście w swoich projektach – zdecydowanie warto.

Źródła i dalsze materiały#