Solução de problemas

Comece aqui quando algo não funcionar. A página nunca quebra quando o Taggor falha (o fallback continua visível), então um problema costuma aparecer como “meu componente não está lá”. Ache o seu caso, rode a conferência, aplique a correção.

Se um comando ou a API imprimiu um erro, abra a página dele: todo erro tem uma em /docs/errors/<código>/ (o docs_url do erro aponta para ela) e todo diagnóstico de build tem uma em /docs/diagnostics/<código>/. Veja Erros da API e da CLI e Diagnósticos de build. Essas páginas ainda estão só em inglês.

O componente não aparece

Siga a lista; a primeira linha que não se confirma é a causa.

Conferir	Como	Se falhar
O snippet está na página	Veja o código-fonte da página e procure o snippet que node taggor.mjs sites snippet imprime (uma tag script cujo endereço termina em /s/<site-key>.js)	Cole uma vez por página, veja Instale o snippet
A tag está escrita na página	A página tem a tag do componente, por exemplo <faq-accordion>	Escreva a tag onde o componente deve aparecer
O componente está anexado ao site	node taggor.mjs attach <componente> --site <site> (repetir é seguro)	Um componente só chega à página depois de anexado ao site
O ambiente do site entrega uma versão	node taggor.mjs versions <componente> lista os canais e a versão de cada um	Um site staging mostra a versão do canal staging e um site production a do canal production; canal vazio não mostra nada. publish move o staging; só o promote move o production
O domínio da página é permitido	Leia o console do navegador	O domínio não é permitido
Nada bloqueia o loader	Procure uma violação ou uma requisição falha no console e na aba de rede	A CSP da página bloqueia o loader; bloqueadores de anúncio também podem barrar a requisição
A tag está livre na página	customElements.get("<tag>") no console	O nome de uma tag conflita
Você não está vendo uma cópia em cache	Espere cerca de dois minutos depois de publicar, promover ou reverter	Uma mudança ainda não apareceu

O Taggor fica em silêncio no console do navegador de propósito quando não monta nada (a página precisa ficar limpa), com uma exceção: o aviso de domínios permitidos abaixo. Um modo debug que explica cada caso está previsto, mas ainda não existe.

O domínio não é permitido

Se o domínio da página não está nos domínios permitidos do site, o loader não monta nenhum componente e imprime um aviso no console, em inglês:

taggor: this page's domain is not in the site's allowed domains, so no component was mounted.

A página segue funcionando e o fallback dentro de cada tag continua visível.

• Adicione o domínio ao site. No portal, edite o site e adicione o domínio; pela CLI, node taggor.mjs sites domains set --site <chave do site> --domain <hostname> troca a lista inteira (informe todos os domínios que o site mantém), e --domain em node taggor.mjs sites create define a lista de um site novo. Escreva o hostname sem esquema, porta nem caminho (www.example.com, não https://www.example.com:8080).
• Uma entrada simples vale para aquele domínio e para a forma com www.. example.com não cobre blog.example.com; adicione *.example.com, que cobre exatamente mais um rótulo. O curinga não cobre o domínio sem prefixo: liste os dois.
• Teste local. localhost é aceito na lista de um site staging. Lista vazia vale como “qualquer página” só num site staging; num site production, lista vazia bloqueia tudo.

A tabela completa de casos está em Domínios permitidos (em inglês). A lista protege contra um snippet copiado, não é controle de acesso: o loader e os bundles são públicos.

A CSP da página bloqueia o loader

Se o seu site envia um Content-Security-Policy, o navegador recusa o snippet quando a política não o permite. O console mostra uma mensagem como Refused to load the script … because it violates the following Content-Security-Policy directive. A página segue de pé e o fallback aparece.

1. Dê ao snippet o nonce da resposta e permita a origem da CDN do seu snippet em script-src.
2. Se você exige Trusted Types, liste a política taggor.
3. Permita a origem da CDN em img-src e font-src só se um componente usa imagens ou fontes, e em connect-src só se um componente envia dados.

A política exata que funciona está em Instale o snippet. Para descobrir qual diretiva bloqueia, envie a política primeiro como Content-Security-Policy-Report-Only e leia as violações: uma violação script-src-elem na CDN quer dizer que falta a origem ou o nonce; uma violação trusted-types quer dizer que taggor não está listada.

O nome de uma tag conflita

A tag de um componente (o nome do Custom Element) é o endereço dele na página, e duas coisas podem colidir.

Dois componentes do mesmo site usam a mesma tag. A API recusa anexar o segundo com tag_conflict (HTTP 409). Desanexe um dos dois (node taggor.mjs detach <componente> --site <site>) ou publique um deles com outra tag.

A tag não é válida. invalid_tag_name (HTTP 400): use letras minúsculas, dígitos e hífens, com pelo menos um hífen (meu-form). O prefixo taggor- é reservado.

Outro script da página já definiu a tag. O navegador aceita uma definição por nome. O Taggor nunca sobrescreve nem redefine uma tag: se a página já tem customElements.get("<tag>"), o componente não é montado e a página fica com o elemento do outro script. Renomeie a tag do componente e publique de novo, ou tire a outra definição. Um nome com prefixo seu (acme-faq) evita a maior parte das colisões.

Uma sombra ou um contorno de foco aparece cortado

Todo componente começa com :host { display: block; contain: content }, que corta o que um elemento pinta fora da caixa do próprio componente. Um botão cuja sombra termina numa linha reta, ou um contorno de foco sem um dos lados, é isso.

• Deixe espaço dentro do componente: padding num elemento interno, pelo menos do tamanho da sombra.
• Ou acrescente :host { contain: none } aos estilos do componente, quando a pintura precisa sair da caixa (um dropdown, um tooltip, a sombra de um botão que ocupa o componente inteiro).

Uma mudança ainda não apareceu

A página carrega o loader do site, que embute a lista de componentes e a versão para a qual cada um aponta. O navegador ou a CDN podem guardar esse loader por 60 segundos, e a plataforma lê a configuração do site com um cache de até 60 segundos também. Então um publish, um promote, um rollback, um attach novo ou uma mudança de domínios permitidos pode levar até cerca de dois minutos para chegar a um visitante.

• Espere dois minutos e recarregue a página.
• Confira para onde aponta o canal do ambiente do site com node taggor.mjs versions <componente>: se é a versão esperada, a plataforma está certa e só a cópia da página é velha.
• O código de uma versão é imutável: quando um componente parece errado depois de o canal andar, o que você vê é a versão nova, não um arquivo velho. Volte com node taggor.mjs rollback <componente> --channel <canal>.

Um rollback ou uma retirada também não é instantâneo para um visitante que já tem o loader antigo, pelos mesmos dois minutos.