Angular e TYPO3

Por que o Angular funciona com o TYPO3, mas a maioria das configurações falha

A ideia é convincente: TYPO3 entrega conteúdo como JSON, Angular renderiza o frontend como Single Page Application. Editores trabalham no backend familiar do TYPO3, desenvolvedores constroem um frontend moderno sem restrições de TypoScript. Na prática, muitos projetos Angular-TYPO3 falham na fronteira arquitetural entre CMS e SPA. A extensão oficial TYPO3 Headless (EXT:headless) resolve o problema de entrega de conteúdo. Mas roteamento, preview, SEO e cache precisam de soluções elaboradas que vão além de um simples ng serve.

Angular como frontend para TYPO3 é adequado para empresas que precisam de conteúdo multi-canal: um site, um app, um portal de intranet e digital signage a partir de uma única fonte de conteúdo. O investimento se paga a partir do segundo canal. Para sites puros sem ambição de app, uma configuração clássica TYPO3-Fluid é quase sempre mais eficiente.

Cenários típicos de uso

Plataformas multi-canal com app e web. Um fornecedor automotivo mantém dados de produtos, informações de serviço e notícias no TYPO3. O site roda como SPA Angular, o app de serviço para técnicos usa a mesma API JSON. Alterações no TYPO3 aparecem em ambos os canais simultaneamente. O conteúdo é mantido uma vez, entregue duas vezes.

Portais de intranet com interação complexa. Dashboards de RH, plataformas de gestão de conhecimento e ferramentas internas se beneficiam da abordagem baseada em componentes do Angular. TYPO3 entrega conteúdo estruturado (políticas, manuais, organogramas), Angular renderiza views interativas com filtros, busca e atualizações em tempo real. A autenticação roda via LDAP/SSO existente, TYPO3 verifica permissões via fe_group.

Configuradores e páginas de produto interativas. Fabricantes de produtos configuráveis utilizam Angular para a visualização 3D ou o configurador. Os dados mestres de produto vêm do TYPO3, a lógica de configuração vive no frontend Angular. Em um cliente com 1.200 variantes configuráveis, essa abordagem reduziu o tempo de carregamento da página do configurador de 4,2 para 1,1 segundos.

Arquitetura técnica

A extensão TYPO3 Headless transforma a saída padrão de HTML em JSON. Cada elemento de conteúdo, cada navegação, cada nível de breadcrumb é entregue como objeto JSON. Angular consome essa API via serviços HttpClient.

A arquitetura consiste em três camadas. TYPO3 como backend entrega conteúdo pela API Headless em /api/. Angular como aplicação frontend é compilado como processo de build próprio (ng build --prod) e tipicamente servido via CDN ou servidor web separado. Entre eles fica um servidor SSR baseado em Node.js (Angular Universal), que cuida do Server-Side Rendering para SEO e redes sociais.

O roteamento é dividido: Angular Router cuida da navegação client-side, TYPO3 define a estrutura de URLs via Site Configuration. Ambos devem permanecer sincronizados. Na prática, isso significa: quando um editor cria uma nova página no TYPO3, Angular precisa conhecer essa URL. A solução é um roteamento dinâmico no frontend Angular que consulta a estrutura de páginas da API TYPO3 a cada build.

Serviços TypeScript são gerados a partir dos tipos de conteúdo TYPO3. Para cada Content Element existe um componente Angular com tipagem. Esses tipos podem ser gerados via script a partir da API TYPO3, garantindo o alinhamento entre backend e frontend.

Problemas frequentes e soluções

Deficiências de SEO por renderização apenas client-side. O Google renderiza JavaScript, mas não de forma confiável e não imediatamente. Sem Server-Side Rendering (Angular Universal ou Angular SSR desde v17), páginas são indexadas tardiamente ou nunca. A solução: usar Angular Universal como camada SSR. A resposta HTML inicial deve estar completamente renderizada antes que o processo de hydration client-side assuma.

Preview de conteúdo no backend TYPO3 não funciona. Editores clicam em “Preview” e veem JSON em vez de uma página renderizada. A solução: configurar um proxy de preview que redireciona a resposta JSON para uma instância Angular de preview dedicada. EXT:headless oferece um modo de preview que entrega conteúdo draft via parâmetro de token.

Problemas de CORS entre API TYPO3 e frontend Angular. Quando TYPO3 e Angular rodam em domínios diferentes, o navegador bloqueia as requisições à API. A extensão EXT:cors ou um reverse proxy server-side resolve esse problema. Recomendado: operar ambos sob o mesmo domínio (TYPO3 em /api/, Angular em /).

Migração e compatibilidade de versões

EXT:headless é oficialmente compatível com TYPO3 v11, v12 e v13. A extensão é mantida ativamente e segue o ciclo de release do TYPO3. Angular tem seu próprio ritmo de release: a cada 6 meses uma nova versão major. Desde Angular v17, SSR está integrado nativamente (sem necessidade de pacote Angular Universal separado).

Para projetos Angular-TYPO3 existentes em TYPO3 v10 ou anterior, recomenda-se uma migração gradual: primeiro atualizar TYPO3 para v12 ou v13, depois Angular para a versão LTS atual (v18). A interface de API da EXT:headless mudou em vários pontos entre v2 e v4, especialmente no tratamento de overlays de idioma e previews de workspace.

O esforço para um projeto Angular-TYPO3 é tipicamente 30-50% acima de um projeto Fluid puro. Esse esforço adicional é recuperado pelo segundo canal (app, intranet). A Gosign orienta antes do início do projeto se Headless é a abordagem correta ou se uma configuração clássica com ilhas JavaScript direcionadas atinge o mesmo objetivo.