Configurar o CSS crítico

O que o módulo faz — e o que não faz

Por cada modelo de página, o Kakapo obtém por HTTP uma página de exemplo real do teu site (apenas na área de administração ou por cron, nunca durante a montagem da página de um visitante), lê diretamente do disco as folhas de estilo locais aí ligadas e verifica cada regra individual com DOMXPath contra o documento. Daí resultam dois produtos: o CSS crítico, que é colocado inline no cabeçalho, e a lista das regras que neste modelo não acertaram em nenhum elemento.

Neste processo não é renderizado nada. Não há navegador, nem viewport, nem posição de deslocamento. “Visível acima” é uma aproximação segundo uma regra divulgada: todos os elementos abaixo de body são numerados, os primeiros 30 por cento (predefinição, ajustável entre 5 e 90) contam como acima, mais tudo o que estiver dentro dos marcos indicados. São sempre incluídos html, body, :root e @font-face, bem como as @keyframes que uma regra crítica designe através de animation. As regras que só atuam por estados (:hover, :focus, :active) ficam de fora, tal como @media print. Onde o procedimento chega ao seu limite, arredonda para cima: a regra conta como acertada. Uns quilobytes a mais custam menos do que uma regra em falta e cintilações.

Verificar os requisitos antes de analisares

Duas coisas têm de estar em ordem. Primeiro, a extensão PHP dom/libxml — o módulo não a verifica através de class_exists(), constrói antes um documento em miniatura e consulta-o de verdade. A razão: alguns alojamentos definem disable_classes=DOMDocument e, nesse caso, class_exists() continua a responder “sim”, mas o new falha. Se a extensão faltar, “Analisar” e “Atualizar diariamente” ficam bloqueados e o motivo aparece ao lado.

Em segundo lugar, o loopback: o site tem de conseguir alcançar-se a si próprio por HTTP. Para isso existe o botão “Verificar loopback” na secção Requisitos; ele guarda o código HTTP, o tamanho da resposta e a duração. Se falhar, falha também qualquer análise — causas típicas são uma firewall à frente do site, uma proteção Basic-Auth no ambiente de staging ou um nome de host que não resolve internamente.

O que a análise não consegue ler também não é adiado: as folhas de estilo de hosts externos, de um CDN ou do Google Fonts continuam a bloquear a renderização, sem alteração. É o caminho lento, mas seguro.

Avançar modelo a modelo

Existem sete modelos: Página inicial, Página do blog, Artigo individual, Página estática, Arquivo, Resultados de pesquisa e Página de erro 404. Cada um é analisado e aprovado individualmente. Se a tua página inicial mostrar a lista de artigos, “Página do blog” não é aplicável — o interruptor fica bloqueado, porque não teria efeito. Se não existir nenhum artigo publicado ou nenhuma página, falta a página de exemplo e o modelo fica igualmente bloqueado.

O caminho recomendado: primeiro “Analisar todos” ou analisar individualmente. Depois abres, para um modelo, “Pré-visualização” e “sem” em dois separadores — é a mesma página real, uma vez com e outra sem tratamento, visível apenas para administradores com sessão iniciada e apenas com uma chave de utilização única válida no endereço. Para isso, o interruptor principal não precisa de estar ligado. A cintilação durante a montagem vê-se de forma mais fiável num separador próprio com a ligação limitada, e não no quadro incorporado.

Só quando a comparação parecer limpa é que aprovas o modelo e ligas o interruptor principal. Ele começa em modo de teste: aí só os administradores com sessão iniciada veem o tratamento, para todos os outros a página fica inalterada. Só passas para “ativo” depois de teres revisto vários modelos.

Os quatro travões e as listas de exceções

“Carregar de forma adiada as folhas de estilo analisadas” é a verdadeira poupança de tempo. Desligado significa: o CSS crítico entra adicionalmente inline e tudo o resto fica como estava — sem risco, mas também sem ganho. Ligado significa: as folhas de estilo avaliadas carregam com media="print" mais um repositor onload, com um duplicado noscript para visitantes sem JavaScript. É adiado exclusivamente aquilo que foi realmente lido, e apenas quando o handle e o endereço do ficheiro ainda correspondem ao que foi analisado.

“Suspender quando os ficheiros de origem mudarem” memoriza, para cada ficheiro avaliado, a hora de alteração e o tamanho, bem como o tema ativo. Se algo mudar, não há qualquer tratamento, em vez de um tratamento com CSS crítico possivelmente errado — no código-fonte fica então uma nota com o motivo.

Três campos de texto são a saída de emergência. URLs de exclusão: uma linha por caminho, “*” como marcador de posição; estas páginas nunca são tratadas (tipicamente /checkout*, /mein-konto*). Nunca adiar folhas de estilo: um handle do WordPress por linha, predefinidos admin-bar e dashicons. Marcos: um seletor por linha, tudo o que estiver lá dentro conta como acima — predefinidos são header, [role="banner"], .site-header, #masthead, nav, .main-navigation, .site-branding, .hero e h1. As linhas que não podem ser interpretadas são recusadas em vez de guardadas em silêncio.

Uma alteração à percentagem “acima” ou aos marcos só produz efeito depois de uma nova análise. Tudo o resto descarta imediatamente a cache de páginas, porque aí está guardado HTML já pronto com o estado antigo.

Quando algo corre mal

“Orçamento de tempo esgotado”: a execução atingiu 25 segundos ou o limite de tempo do PHP. O relatório está guardado, o CSS crítico não, de propósito — um CSS crítico incompleto provocaria cintilações. A mensagem indica o ficheiro em que parou. Analisa de novo ou retira uma folha de estilo muito grande através da lista de exceções.

“Respondeu com HTTP …”: a página de exemplo não devolveu o código esperado (200; na página de erro, 404). Não é guardado nada. Verifica se a página está acessível no navegador e se existe alguma proteção à frente dela.

Um modelo está como “desatualizado”: um ficheiro CSS avaliado mudou ou o tema foi trocado. Voltar a analisar. Se aí estiver “outra percentagem”, o modelo foi criado com um valor percentual diferente do que está agora definido — voltar igualmente a analisar.

Para que isso não fique em trabalho manual, existe “Verificar e atualizar diariamente”. A execução por cron analisa apenas modelos que já estejam aprovados e desatualizados; nunca liga nada e não cria qualquer análise para um modelo não aprovado. O seu último resultado aparece como nota na secção Cinto de segurança.

Se ainda assim uma página continuar instável, ajuda olhar para o código-fonte: aí está um comentário com o modelo tratado e o estado (pré-visualização, modo de teste, ativo) ou o motivo pelo qual não foi tratada de propósito.