Routing oparty na haszu a routing oparty na ścieżce

SPA potrzebują adresów URL, których przeglądarka nie pobiera. Istnieją dwa podejścia: oparte na haszach wykorzystuje fragment (wszystko po znaku #), którego przeglądarka nigdy nie wysyła do serwera, a oparte na ścieżkach wykorzystuje pathname wraz z mechanizmami History API.

Adresy URL wyglądają tak: https://example.com/#/about. Serwer widzi tylko / i zwraca ten sam kod HTML dla każdego adresu URL. JavaScript po stronie klienta odczytuje location.hash, aby zdecydować, który widok wyrenderować. To proste rozwiązanie, które nie wymaga konfiguracji serwera.

Routery oparte na haszach nasłuchują zdarzenia hashchange, które jest wywoływane za każdym razem, gdy zmienia się location.hash. W połączeniu z odczytem window.location.hash jest to całe API potrzebne do routingu po stronie klienta — History API nie jest wymagane.

Adresy URL wyglądają tak: https://example.com/about — nie można ich odróżnić od adresów URL stron renderowanych przez serwer. Metoda pushState z History API zmienia ścieżkę bez przeładowania; popstate jest wywoływane podczas nawigacji wstecz i do przodu; przechwytywanie kliknięć zamienia elementy <a> w nawigację SPA.

W przypadku routingu opartego na ścieżkach serwer musi zwracać plik index.html SPA dla każdej ścieżki, którą użytkownik może bezpośrednio otworzyć (lub odświeżyć). W przeciwnym razie odświeżenie /about zakończy się błędem 404. Należy skonfigurować serwer tak, aby najpierw próbował znaleźć plik, a następnie korzystał z index.html jako rozwiązania awaryjnego (history fallback w Nginx, vite-plugin-history-api w Vite dev).

Wyszukiwarki i wiele narzędzi w ogóle nie potrafią indeksować fragmentów haszowych — zawartość pod adresem /#/about jest niewidoczna dla starszych robotów (Google obsługuje ją za pomocą renderowania bez interfejsu graficznego, ale inne narzędzia mogą tego nie robić). Adresy URL oparte na ścieżkach są indeksowane standardowo, dzięki czemu zdecydowanie lepiej sprawdzają się w SEO.

Adresy URL z haszami wyglądają wyraźnie „dziwnie” — użytkownicy zauważają znak # i mogą nie ufać odnośnikowi lub zapomnieć skopiować pełny URL. Adresy URL oparte na ścieżkach wyglądają jak wszystkie inne adresy internetowe, czyli tak, jak oczekują tego użytkownicy. Współczesne SPA niemal zawsze wybierają z tego powodu routing oparty na ścieżkach.

Oparte na haszach: około 10 wierszy JavaScriptu (detektor hashchange + renderowanie). Oparte na ścieżkach: wywołania pushState, detektor popstate, przechwytywanie kliknięć odnośników i awaryjne przekierowanie po stronie serwera. Hasze to najprostsze możliwe rozwiązanie; ścieżki wymagają dodatkowej infrastruktury, ale zapewniają lepsze wrażenia użytkownika.

Hosting wyłącznie statyczny (przy domyślnej konfiguracji GitHub Pages) nie obsługuje awaryjnego przekierowania po stronie serwera, więc routing oparty na ścieżkach przestaje działać po odświeżeniu. Możliwe rozwiązania to sztuczki z przekierowaniem w 404.html, hosting w Netlify/Vercel (które obsługują awaryjne przekierowanie SPA) albo wybór routingu opartego na haszach w projektach przeznaczonych wyłącznie dla hostingu statycznego.

Niektóre aplikacje łączą oba rozwiązania: routing oparty na ścieżkach dla głównej trasy oraz hasze dla sekcji wewnątrz strony (modali i kotwic kart). Zdarzenie hashchange jest nadal wywoływane w takich przypadkach, uzupełniając router oparty na History o obsługę stanu podstron bez zaśmiecania głównego URL.

Aby przejść z haszów na ścieżki, należy przepisać wszystkie odnośniki wewnętrzne, dodać awaryjne przekierowanie po stronie serwera, zastąpić logikę hashchange przez popstate, a stare adresy URL z haszami przekierować do odpowiedników opartych na ścieżkach za pomocą niewielkiego skryptu uruchamianego podczas inicjalizacji, który wykona się raz i wywoła history.replaceState.

Routing oparty na haszach należy wybrać w przypadku: hostingów statycznych bez możliwości przepisywania adresów, wewnętrznych narzędzi administracyjnych, w których SEO nie ma znaczenia, oraz osadzanych widżetów. Routing oparty na ścieżkach należy wybrać w przypadku: wszystkiego, co jest przeznaczone dla użytkowników, powinno być indeksowane przez SEO lub ma być udostępniane w mediach społecznościowych — czyli w przypadku większości aplikacji.

Dlaczego routing SPA oparty na ścieżkach wymaga konfiguracji serwera, a routing oparty na haszach jej nie wymaga?

Routing oparty na haszach (adresy URL takie jak /#/about) nie wymaga konfiguracji serwera, ale ma słabe wsparcie SEO i wykorzystuje nieestetyczne adresy URL. Routing oparty na ścieżkach (adresy URL takie jak /about) wymaga awaryjnego przekierowania do index.html, ale zapewnia przejrzyste adresy URL przyjazne SEO i łatwe do udostępniania. Współczesne SPA przeznaczone dla użytkowników korzystają z routingu opartego na ścieżkach; projekty statyczne lub wewnętrzne mogą nadal wybierać hasze ze względu na prostotę.