Como Construir Sua Primeira Extensão para Firefox

Tutorial de criação de extensões para Firefox com Manifest V3 e WebExtensions APIs, cobrindo content scripts, interfaces popup e permissões mínimas.

OpenReplay Team

Nov 14, 2025 · 4 min read

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.

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 activeTab quando 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 .js externos
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

Posso usar o mesmo código de extensão para Chrome e Firefox?

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.

Por que minha extensão só funciona em páginas example.com?

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.

Como faço para publicar minha extensão do Firefox na loja de Add-ons?

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.

Qual é a diferença entre content scripts e background scripts no MV3?

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.