Como Se Escreve Extensão

O que é uma extensão e por onde começar

Extensão é um programa que roda dentro do navegador, adicionando funcionalidades à página ou ao próprio navegador. Pode ser algo simples como um botão que altera cores, ou algo mais complexo que injeta scripts, modifica requisições e lê dados do histórico. A estrutura básica de uma extensão envolve um arquivo chamado manifest, que diz ao navegador o que o código pode fazer, quais permissões pede e onde estão os arquivos do projeto. Sem esse arquivo, o navegador simplesmente ignora o diretório.

Como se escreve extensão passo a passo

Comece criando uma pasta vazia no seu computador. Dentro dela, crie um arquivo chamado manifest.json. Esse é o coração da extensão. O conteúdo mínimo seria algo assim: {
"manifest_version": 3,
"name": "Minha Extensão",
"version": "1.0",
"description": "Uma extensão qualquer",
"permissions": ["activeTab"]
}

Salve isso e abra o Chrome. Vá em chrome://extensions, ative o modo desenvolvedor no canto superior direito e clique em "Carregar descompactada". Selecione a pasta. A extensão vai aparecer na lista. Se nada acontecer, verifique o arquivo manifest. Erro de formatação JSON é o problema mais comum que eu vejo. Uma vírgula sobrando, uma aspa faltando, e a extensão inteira não carrega. O navegador não mostra mensagem de erro clara na maioria das vezes. Só simplesmente não aparece. Para dar vida à extensão, adicione um script JavaScript. No manifest, você aponta para ele usando a chave "content_scripts" ou "background". Cada um faz uma coisa diferente.

Content scripts rodam no contexto da página que você está visitando. Eles podem ler o DOM, injetar estilos, detectar botões e clicar neles automaticamente. O problema é que eles não têm acesso direto à API do navegador. Se você precisar chamar chrome.storage ou enviar dados para um servidor, tem que usar mensagens entre o content script e o background. Background scripts (ou service workers, no Manifest V3) ficam rodando independentemente das páginas abertas. Eles controlam abas, ouvem eventos do navegador e gerenciam o estado da extensão. É onde você coloca a lógica principal que não depende de uma página específica. Um exemplo prático: eu precisava criar uma extensão que monitorava mudanças de preço em uma loja específica. O content script lia os elementos da página e extraía o preço atual. Quando detectava uma variação, enviava uma mensagem para o background, que salva no storage do usuário e mostrava uma notificação. Simples assim.

O problema foi que a loja atualizava os preços via JavaScript, e o content script às vezes lia um valor antes da página terminar de carregar. A solução foi adicionar um listener de mutations no DOM, esperando o elemento de preço estabilizar antes de ler. Usei um intervalo que verificava se o preço mudava duas vezes seguidas com o mesmo valor, o que indicava que a página tinha terminado de renderizar. Não é elegante, mas funciona na prática.

Detalhes que ninguém conta

A diferença entre Manifest V2 e V3 mudou muita coisa. No V2, o background era um service worker persistente. No V3, ele vira um service worker que mora e morre conforme a necessidade. Isso significa que variáveis globais somem quando o worker é destruído. Se você estava acostumado a guardar dados em variáveis, precisa migrar para o chrome.storage ou sessionStorage. Outro detalhe importante: as extensões V3 não permitem eval() nem strings dinâmicas para executar código. Isso quebra algumas bibliotecas antigas que usavam essa técnica. Se sua extensão depende de algo assim, você terá que refatorar. Permissões são outro ponto que gera confusão. Cada permissão que você pede no manifest pode ser vista pelo usuário durante a instalação. Pedir acesso a "all_urls" sem motivo faz a maioria das pessoas desistirem na hora. Use sempre o mínimo necessário. Para a maior parte das extensões, "activeTab" resolve, porque ele dá acesso à aba ativa apenas quando o usuário clica no ícone da extensão.

Se quiser publicar na Chrome Web Store, o processo de revisão leva de alguns dias a algumas semanas. Extensões com muitas permissões ou que acessam dados sensíveis passam por uma análise mais demorada. Prepare o readme, adicione screenshots e descreva claramente o que a extensão faz. Revendedores de extensão na loja já me viram reprovar sem motivo claro. Na maioria das vezes, volta para revisão depois de ajustar a descrição ou remover alguma permissão desnecessária.

Testando sem publicar

Você não precisa publicar para testar. O modo desenvolvedor do Chrome permite carregar extensões locais a qualquer momento. Sempre que fizer uma alteração nos arquivos, clique no botão de recarregar na página chrome://extensions. Não feche e abra de novo, só o recarregar. Use o console de desenvolvimento do navegador também. F9 abre o DevTools normalmente, mas há uma aba específica para extensions que mostra logs, erros e status de cada extensão instalada. É muito mais rápido que depender de alertas ou console.log espalhados pelo código. Existe ainda o chrome.debugger, que permite anexar um debug remoto diretamente ao service worker da extensão. Útil quando o worker mata e revive rapidamente e você não consegue colocar breakpoints com facilidade.

Erros comuns de quem começa

Esquecer de adicionar o ícone. O Chrome exige pelo menos um ícone de 128x128 pixels no manifest. Se você não colocar, a extensão funciona, mas a loja rejeita na publicação. Tentar acessar cookies de outros domínios. Sem a permissão específica de host, você não consegue ler cookies de sites que não sejam o da própria extensão. Isso vale para requests XMLHttpRequest e fetch também. Confundir content scripts com o background. Muitos iniciantes tentam manipular o DOM diretamente no service worker e se perguntam por que nada funciona. O background não vê a página. Ele só interage com ela quando recebe uma mensagem do content script.

Não tratar erros de rede. Se sua extensão faz uma requisição para uma API externa e a conexão falha, o erro silencioso é o cenário mais comum. Sempre use try-catch e verifique o status da resposta antes de processar os dados.

Alternativas e ferramentas úteis

Para desenvolvimento rápido, o Extension Manifest V3 Viewer (disponível como extensão) ajuda a inspecionar o conteúdo do manifest e validar se tudo está correto antes de carregar localmente. O Firefox Developer Tools também possui uma aba de Extensions integrada, com visualização de logs e capacidade de injetar código em tempo real. Se você desenvolver para múltiplos navegadores, vale a pena testar no Firefox além do Chrome. Existem templates prontos no GitHub que já vêm configurados com build automation, linting e suporte a TypeScript. Usar um template economiza horas de configuração inicial, embora possa esconder alguns detalhes importantes de como a extensão funciona por baixo dos panos. Vale a pena dar uma olhada no código gerado antes de começar a desenvolver.

Desenvolver extensão não é complicado no início. A curva de aprendizado mais íngreme vem quando você precisa lidar com timing de carregamento, comunicação entre scripts e limitações do Manifest V3. Com prática, esses problemas se tornam rotineiros. O principal é testar frequentemente, manter o código organizado desde o primeiro commit e não adicionar permissões que você não vai usar.