Como Construir Sua Primeira Extensão para Firefox
Construir uma extensão para Firefox pode parecer intimidante, mas com o Manifest V3 e as APIs modernas de WebExtensions, você pode criar sua primeira extensão funcional em menos de 10 minutos. Este tutorial de extensão para Firefox irá guiá-lo na criação de uma extensão MV3 funcional que modifica páginas web e inclui uma interface popup.
Principais Conclusões
- Crie uma extensão funcional para Firefox usando Manifest V3 em menos de 10 minutos
- Construa content scripts que modificam páginas web de forma segura em contextos isolados
- Implemente interfaces popup para interação do usuário com passagem de mensagens
- Siga as melhores práticas de segurança com permissões mínimas e scripts externos
O Que São WebExtensions e Por Que Manifest V3?
WebExtensions são complementos compatíveis entre navegadores construídos com tecnologias web padrão—HTML, CSS e JavaScript. O Firefox WebExtensions Manifest V3 representa o padrão atual para desenvolvimento de extensões, oferecendo segurança aprimorada através de service workers, melhor desempenho com APIs declarativas e maior compatibilidade entre navegadores.
Embora o Firefox ainda suporte o Manifest V2, começar com o Manifest V3 garante que sua extensão permaneça compatível com futuras atualizações do navegador e se alinhe com a arquitetura de extensões do Chrome, Edge e Safari. Este guia foca exclusivamente nas melhores práticas do MV3.
Configurando a Estrutura do Projeto da Sua Extensão para Firefox
Vamos construir sua primeira extensão para Firefox passo a passo. Crie uma nova pasta chamada my-first-extension e adicione estes arquivos essenciais:
Criando a Configuração do Manifest V3
O arquivo manifest.json é o coração de qualquer extensão. Crie este arquivo com a seguinte configuração Manifest V3:
{
"manifest_version": 3,
"name": "My Page Enhancer",
"version": "1.0.0",
"description": "Enhances web pages with custom styling",
"action": {
"default_popup": "popup.html",
"default_icon": {
"48": "icon.png"
}
},
"content_scripts": [
{
"matches": ["*://*.example.com/*"],
"js": ["content.js"]
}
],
"icons": {
"48": "icon.png"
}
}Note o uso de "action" em vez do obsoleto "browser_action"—este é um requisito fundamental para o Firefox MV3. O manifest segue os princípios de permissões mínimas, uma prática essencial para extensões do Firefox.
Construindo o Content Script para Modificação de Páginas
Os content scripts do MV3 são executados em um contexto isolado, protegendo o código da sua extensão de scripts maliciosos da página. Crie o content.js:
// content.js - Runs on matching pages
console.log('Extension loaded on:', window.location.href);
// Add a subtle border to all paragraphs
document.querySelectorAll('p').forEach(paragraph => {
paragraph.style.border = '2px solid #4A90E2';
paragraph.style.padding = '8px';
paragraph.style.borderRadius = '4px';
});
// Listen for messages from the popup
browser.runtime.onMessage.addListener((request, sender, sendResponse) => {
if (request.action === 'changeColor') {
document.body.style.backgroundColor = request.color;
}
});Isto demonstra como o Manifest V3 isola o código da extensão do contexto da página, prevenindo vulnerabilidades de segurança comuns em arquiteturas de extensões mais antigas.
Discover how at OpenReplay.com.
Criando a Interface Popup de Action do Firefox
O componente popup de action fornece interação com o usuário. Crie o popup.html:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body {
width: 300px;
padding: 16px;
font-family: system-ui, -apple-system, sans-serif;
}
button {
width: 100%;
padding: 8px;
margin: 4px 0;
cursor: pointer;
}
</style>
</head>
<body>
<h2>Page Enhancer</h2>
<button id="blue">Blue Background</button>
<button id="green">Green Background</button>
<script src="popup.js"></script>
</body>
</html>Adicione o popup.js correspondente para lidar com as interações do usuário:
// popup.js - Handles popup interactions
document.getElementById('blue').addEventListener('click', () => {
sendColorChange('#E3F2FD');
});
document.getElementById('green').addEventListener('click', () => {
sendColorChange('#E8F5E9');
});
async function sendColorChange(color) {
const [tab] = await browser.tabs.query({
active: true,
currentWindow: true
});
browser.tabs.sendMessage(tab.id, {
action: 'changeColor',
color: color
});
}Carregando e Testando Seu Add-on JavaScript para Firefox
Para testar seu add-on JavaScript para Firefox:
- Abra o Firefox e navegue até
about:debugging - Clique em “Este Firefox” na barra lateral esquerda
- Clique em “Carregar Extensão Temporária”
- Selecione qualquer arquivo da pasta da sua extensão
O ícone da sua extensão aparece na barra de ferramentas. Visite qualquer página example.com para ver o content script em ação. Clique no ícone da extensão para abrir o popup e testar as mudanças de cor de fundo.
Quando você modificar arquivos, clique em “Recarregar” em about:debugging para aplicar as mudanças instantaneamente—sem necessidade de reiniciar o navegador.
Melhores Práticas para Extensões do Firefox no Desenvolvimento MV3
Seguir estas melhores práticas para extensões do Firefox garante que sua extensão passe na revisão e forneça uma experiência segura ao usuário:
- Permissões Mínimas: Solicite apenas
activeTabquando precisar de acesso à aba atual, evitando permissões amplas de host - Sem JavaScript Inline: A Content Security Policy do MV3 bloqueia scripts inline—sempre use arquivos
.jsexternos - Service Workers: Para tarefas em segundo plano, use service workers (não coberto aqui, mas essencial para recursos avançados)
- Comunicação Segura: Use
browser.runtime.sendMessage()para comunicação entre componentes
Conclusão
Você construiu com sucesso uma extensão funcional para Firefox usando Manifest V3. A transição de content scripts simples para extensões completas segue este mesmo padrão: contextos isolados, passagem de mensagens e permissões mínimas. Domine estes fundamentos e você construirá extensões seguras e performáticas nas quais os usuários confiam.
Para expandir suas habilidades, explore a Storage API para persistir preferências do usuário, implemente service workers em segundo plano para manipulação complexa de eventos e revise a documentação mais recente de WebExtensions do MDN para atualizações de API.
Perguntas Frequentes
Sim, WebExtensions usando Manifest V3 são amplamente compatíveis entre navegadores. Existem pequenas diferenças nos namespaces de API onde o Chrome usa chrome e o Firefox usa browser, mas o Firefox suporta ambos para compatibilidade.
O arquivo manifest.json especifica padrões de correspondência na seção content_scripts. Altere o array matches para incluir outros domínios ou use padrões mais amplos como *://*/* para todos os sites, embora isso exija consideração cuidadosa de segurança.
Empacote sua extensão como um arquivo ZIP, crie uma conta de desenvolvedor em addons.mozilla.org, envie sua extensão para revisão e aguarde a aprovação. O Firefox normalmente revisa extensões em 24-48 horas.
Content scripts são executados em contextos de páginas web e podem acessar e modificar elementos DOM. Background scripts no MV3 usam service workers que lidam com eventos e chamadas de API, mas não podem acessar diretamente o conteúdo da página, exigindo passagem de mensagens para comunicação.
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.
