Angular i TYPO3

Dlaczego Angular z TYPO3 działa, ale większość konfiguracji kończy się niepowodzeniem

Koncepcja brzmi przekonująco: TYPO3 dostarcza treści jako JSON, Angular renderuje frontend jako Single Page Application. Redaktorzy pracują w znanym backendzie TYPO3, developerzy budują nowoczesny frontend bez ograniczeń TypoScript. W praktyce wiele projektów Angular-TYPO3 rozbija się o granicę architektoniczną między CMS a SPA. Oficjalne rozszerzenie TYPO3 Headless (EXT:headless) rozwiązuje problem dostarczania treści. Ale routing, podgląd, SEO i caching wymagają przemyślanych rozwiązań wykraczających poza proste ng serve.

Angular jako frontend dla TYPO3 nadaje się dla przedsiębiorstw potrzebujących treści wielokanałowych: strona internetowa, aplikacja, portal intranetowy i Digital Signage z jednego źródła treści. Inwestycja zwraca się od drugiego kanału. Dla stron internetowych bez ambicji aplikacyjnych klasyczne TYPO3-Fluid-Setup jest prawie zawsze wydajniejsze.

Typowe scenariusze zastosowania

Platformy wielokanałowe z aplikacją i stroną. Dostawca motoryzacyjny zarządza danymi produktów, informacjami serwisowymi i aktualnościami w TYPO3. Strona działa jako Angular-SPA, aplikacja serwisowa dla techników korzysta z tego samego JSON-API. Zmiany w TYPO3 pojawiają się na obu kanałach jednocześnie. Treść jest utrzymywana raz, dostarczana dwukrotnie.

Portale intranetowe ze złożoną interakcją. Dashboardy HR, platformy zarządzania wiedzą i narzędzia wewnętrzne korzystają z komponentowego podejścia Angulara. TYPO3 dostarcza ustrukturyzowaną treść (polityki, podręczniki, organigramy), Angular renderuje interaktywne widoki z filtrami, wyszukiwaniem i aktualizacjami w czasie rzeczywistym. Autoryzacja odbywa się przez istniejące LDAP/SSO, TYPO3 sprawdza uprawnienia przez fe_group.

Konfiguratory i interaktywne strony produktowe. Producenci konfigurowalnych produktów używają Angulara do widoku 3D lub konfiguratora. Dane podstawowe produktu pochodzą z TYPO3, logika konfiguracji żyje w frontendzie Angular. U klienta z 1200 konfigurowalnymi wariantami podejście to skróciło czas ładowania strony konfiguratora z 4,2 do 1,1 sekundy.

Architektura techniczna

Rozszerzenie TYPO3 Headless transformuje standardowe wyjście z HTML na JSON. Każdy element treści, każda nawigacja, każdy poziom breadcrumb jest dostarczany jako obiekt JSON. Angular konsumuje to API przez serwisy HttpClient.

Architektura składa się z trzech warstw. TYPO3 jako backend dostarcza treści przez Headless-API pod /api/. Angular jako aplikacja frontendowa jest kompilowana jako osobny proces budowania (ng build --prod) i typowo dostarczana przez CDN lub osobny serwer WWW. Pomiędzy nimi znajduje się serwer SSR oparty na Node.js (Angular Universal), który obsługuje Server-Side Rendering dla SEO i sieci społecznościowych.

Routing jest dwudzielny: Angular Router obsługuje nawigację po stronie klienta, TYPO3 definiuje strukturę URL przez Site Configuration. Oba muszą być zsynchronizowane. W praktyce oznacza to: gdy redaktor tworzy nową stronę w TYPO3, Angular musi znać ten URL. Rozwiązaniem jest dynamiczny routing w frontendzie Angular, który przy każdym buildzie pobiera strukturę stron z API TYPO3.

Serwisy TypeScript są generowane z typów treści TYPO3. Dla każdego Content Element istnieje Angular Component z typingiem. Te typy można generować skryptem z API TYPO3, co zapewnia synchronizację między backendem a frontendem.

Częste problemy i rozwiązania

Deficyty SEO przez rendering wyłącznie po stronie klienta. Google renderuje JavaScript, ale nie niezawodnie i nie natychmiastowo. Bez Server-Side Rendering (Angular Universal lub Angular SSR od v17) strony są indeksowane późno lub wcale. Rozwiązanie: wdrożenie Angular Universal jako warstwy SSR. Początkowa odpowiedź HTML musi być w pełni wyrenderowana, zanim proces hydracji po stronie klienta przejmie kontrolę.

Podgląd treści w backendzie TYPO3 nie działa. Redaktorzy klikają “Podgląd” i widzą JSON zamiast wyrenderowanej strony. Rozwiązanie: konfiguracja proxy podglądu, który przekierowuje odpowiedź JSON do dedykowanej instancji podglądu Angular. EXT:headless oferuje tryb podglądu, który dostarcza wersje robocze treści przez parametr tokena.

Problemy CORS między API TYPO3 a frontendem Angular. Gdy TYPO3 i Angular działają na różnych domenach, przeglądarka blokuje żądania API. Rozszerzenie EXT:cors lub serwerowy reverse proxy rozwiązuje ten problem. Zalecenie: oba pod tą samą domeną (TYPO3 pod /api/, Angular pod /).

Migracja i kompatybilność wersji

EXT:headless jest oficjalnie kompatybilne z TYPO3 v11, v12 i v13. Rozszerzenie jest aktywnie utrzymywane i podąża za cyklem wydań TYPO3. Sam Angular ma własny rytm wydań: co 6 miesięcy nowa wersja major. Od Angular v17 SSR jest natywnie zintegrowany (nie jest potrzebny oddzielny pakiet Angular Universal).

Dla istniejących projektów Angular-TYPO3 na TYPO3 v10 lub starszym zaleca się migrację etapową: najpierw aktualizacja TYPO3 do v12 lub v13, potem Angular do aktualnej wersji LTS (v18). Interfejs API EXT:headless zmienił się między v2 a v4 w kilku miejscach, szczególnie w obsłudze nakładek językowych i podglądów Workspace.

Nakład pracy dla projektu Angular-TYPO3 jest typowo o 30-50% wyższy niż dla czystego projektu Fluid. Tę dodatkową inwestycję odzyskuje się dzięki drugiemu kanałowi (aplikacja, intranet). Gosign doradza przed rozpoczęciem projektu, czy Headless jest właściwym podejściem, czy może klasyczne rozwiązanie z celowymi wyspami JavaScript spełni ten sam cel.