Como Se Escreve Extensão

Como realmente se escreve uma extensão de navegador hoje em dia

Achei que ia ser mais complicado no início, mas depois que você entende o fluxo básico, a coisa entra num ritmo rápido. O padrão agora é o Manifest V3, então esquece qualquer tutorial que mencione service workers e background pages clássicas — o Chrome mudou isso há um tempo e as extensões antigas foram descontinuadas. Se você está começando agora, já entra direto no novo modelo. O arquivo central é o manifest.json. Sem ele, nada funciona. É só um JSON simples com algumas chaves obrigatórias: a versão do manifesto (v3), o nome da extensão, uma versão numérica e os escopos de permissão. O Chrome exige que tudo seja servido via HTTPS também quando você testar fora do modo desenvolvedor.

O que significa como se escreve extensão na prática

Na prática, escrever uma extensão é montar quatro peças que precisam conversar entre si: o manifesto, os scripts de conteúdo, os popups ou side panels, e o service worker. Os scripts de conteúdo são o que realmente vê e interage com a página. O service worker cuida dos eventos globais, como when the extension icon is clicked or a message arrives. O popup é a interface que aparece quando clica no ícone da barra de ferramentas. Uma coisa que todo mundo erra na primeira vez: colocar lógica pesada no service worker. Ele tem um tempo de vida curto e pode ser morto pelo navegador a qualquer momento. Se você fizer processamento demorado lá, a extensão simplesmente para de responder no meio do caminho. Jogue essa lógica para um script de conteúdo ou para uma API externa.

Aqui vai um exemplo bem básico do que o manifest precisa ter: { "manifest_version": 3, "name": "Minha Extensão", "version": "1.0", "description": "Faz algo simples", "permissions": ["storage", "tabs"], "action": { "default_popup": "popup.html", "default_icon": "icon.png" }, "content_scripts": [ { "matches": ["https://*.exemplo.com/*"], "js": ["content.js"] } ] }

Perceba que não usei background mais. No V3, isso vira "service_worker". A diferença não é só visual — o service worker não mantém estado entre rodadas, então se você precisar guardar dados entre execuções, use chrome.storage.sync ou localStorage via scripts de conteúdo.

O passo a passo que realmente funciona

Comece pelo mais simples possível. Não tente construir algo com cinquenta linhas antes de validar que a estrutura básica funciona. Crie uma pasta, coloque o manifest.json, adicione um popup.html mínimo com um botão e um content.js que apenas faz um console.log. Carregue via chrome://extensions com o modo desenvolvedor ativado e veja se aparece na lista. Se a extensão não aparece, o erro quase sempre está no manifest. O Chrome é extremamente rigoroso com sintaxe JSON. Uma vírgula sobrando, uma chave mal fechada, e nada funciona. Sem erro visível também — só fica silenciado. Abra o popup de detalhes da extensão na mesma página chrome://extensions e clique em "Ver erros". Isso mostra exatamente onde o problema está.

Depois que a base funciona, adicione funcionalidade aos poucos. Se você precisa ler conteúdo de uma página, isso vai no content script. Se precisa modificar a página, também vai no content script usando DOM APIs normais. Se precisa de comunicação entre o popup e a página, use chrome.runtime.sendMessage e chrome.runtime.onMessage. Um detalhe que causa dor de cabeça constante: as regras de content security policy. No V3, scripts inline são proibidos. Não adianta colocar um onclick direto no HTML ou um script dentro de uma tag script sem src. Tudo precisa vir de arquivos externos. Li isso na documentação oficial depois de perder duas horas debugando um botão que não respondia.

Outro ponto: a diferença entre permissions e host_permissions. Permissões como "tabs" ou "storage" são de longo prazo e pedem aprovação no Chrome Web Store. Host permissions, usados para acessar URLs específicas, podem ser declarados no manifest ou pedidos dinamicamente via requestHostPermission. Para extensões que precisam de acesso a domínios variáveis, o pedido dinâmico é a única saída viável.

Um problema real que eu enfrentei

Estava desenvolvendo uma extensão que precisava capturar o conteúdo de input em tempo real e enviá-lo para um endpoint meu. A solução óbvia seria usar um content script com um event listener de input. Funcionou perfeitamente em teste local. Quando distribuí para usuários beta, o Chrome bloqueou as requisições porque o conteúdo do manifest.json não declarava a url do servidor no campo "host_permissions". Erro bobo, mas difícil de encontrar porque o console do content script não mostra nada de errado — a requisição simplesmente morre silenciosamente. A correção foi adicionar "https://meu-servidor.com/*" ao manifest e pedir a permissão dinamicamente quando o usuário ativa a funcionalidade pela primeira vez. Isso me levou a uma regra prática: nunca confie apenas no manifest para controle de acesso. Sempre valide se as permissões estão presentes no runtime com chrome.permissions.contains antes de fazer qualquer chamada. Se a permissão não estiver lá, peça com chrome.permissions.request e maneje o resultado do usuário.

Alternativas e limitações

Não adianto que este seja o único caminho. Se você precisa de algo mais pesado, com processamento intensivo ou integração profunda com o sistema operacional, uma extensão Electron ou até uma PWA personalizada pode ser mais adequada. Extensões de navegador têm limitações reais de sandbox que você não contorna facilmente. O Chrome Web Store também exige revisão para publicação. O processo leva de alguns dias a algumas semanas, dependendo da complexidade. Se for só para uso pessoal ou equipe interna, instale manualmente arrastando a pasta para chrome://extensions. Para compartilhamento corporativo, considere usar o Chrome for Business ou o Edge Enterprise.

A documentação oficial do Chrome Developers é o melhor material disponível hoje. O guia de migração do V2 para o V3 vale a leitura mesmo que você já tenha experiência anterior, porque há armadilhas que não aparecem em resumos genéricos.