Se você deseja desenvolver extensões de navegador para Chrome, Safari, Firefox, Opera e outros navegadores, provavelmente já viu a frase ‘WebExtension’ em documentos de suporte. Embora WebExtensions e extensões do Chrome sejam termos (um tanto) intercambiáveis para a mesma tecnologia, você precisa estar ciente das diferenças para o desenvolvimento de extensões entre navegadores.
Neste guia, abordaremos a plataforma geral da API que alimenta as extensões do Chrome e WebExtensions, e algumas das armadilhas que você pode encontrar ao criar extensões para vários navegadores da web.
O que é uma WebExtensão?
O Google Chrome adicionou suporte para extensões de navegador pela primeira vez em 2009, e elas rapidamente se tornaram uma parte crítica do sucesso do Chrome. As extensões eram incrivelmente simples de construir, especialmente para qualquer pessoa já familiarizada com JavaScript e desenvolvimento web, e (normalmente) não quebraram quando o Google lançou novas atualizações do Chrome. O Manifest V2 foi a primeira mudança significativa na API de extensão, que o Google começou a aplicar em 2013.
Quando outros navegadores começaram a usar o Chrome como base técnica (ou mais especificamente, o Chromium), eles mantiveram as mesmas APIs de extensão. É por isso que as extensões criadas para o Chrome geralmente funcionam sem modificação no Opera, Vivaldi, Brave, Microsoft Edge, ChatGPT Atlas e outros navegadores baseados no Chromium. A maioria deles pode até instalar extensões da Chrome Web Store do Google, embora navegadores como Opera e Edge também tenham seus próprios repositórios de extensões.
A Mozilla começou a mudar o Firefox para a API de extensão do Chrome em 2015, uma vez que as extensões anteriores baseadas em XUL do Firefox eram complexas e propensas a quebrar a cada atualização do navegador. O Firefox não é baseado no Chromium, portanto, essa mudança exigiu que a Mozilla fizesse engenharia reversa de toda a API. Esta nova implementação foi apelidada de ‘WebExtensions’ e pretendia ser um padrão para vários navegadores.
A Apple também fez engenharia reversa da API de extensão do Chromium para seu navegador Safari, mantendo a mesma marca ‘WebExtension’ da Mozilla. No entanto, a implementação da Apple não é idêntica à da Mozilla ou às APIs encontradas no Chromium.
WebExtensions pode parecer um padrão universal, mas é muito mais disperso do que o desenvolvimento web moderno. Na verdade, está muito mais próximo do desenvolvimento web dos anos 2000, onde as APIs e as capacidades de renderização variavam drasticamente de navegador para navegador (boa viagem, folhas de estilo somente para IE). Para citar o capitão Barbosa, “o código é mais o que você chamaria de diretrizes do que regras reais”.
WebExtensions vs. extensões do Chrome
A principal diferença entre WebExtensions e a extensão normal do Chrome é levar em consideração o comportamento de cada navegador da web e garantir que as APIs necessárias sejam suportadas em todos os navegadores disponíveis. MDN é o melhor recurso para essas informações, com a página de cada API e recurso incluindo uma tabela de compatibilidade de navegador e notas sobre suporte entre navegadores.
Se você criar um site moderno para o Chrome, ele geralmente funcionam sem modificações no Firefox e Safari, porque os fornecedores de navegadores se unem em esforços como os padrões da web W3C e Interop. O mesmo é não verdadeiro para extensões de navegador. O Google tem alguma participação na comunidade WebExtensions, mas as novas APIs do Chromium geralmente demoram um pouco para aparecer no Firefox ou Safari (se é que aparecem), e cada navegador tem seu próprio subconjunto de recursos exclusivos.
Um exemplo é a API sidebarAction, que foi originalmente criada pelo navegador Opera para que as extensões pudessem fornecer páginas da barra lateral. Posteriormente, o Firefox duplicou esse recurso, disponibilizando recursos da barra lateral nas extensões do Firefox e do Opera, mas não no Chrome. Quando o Google finalmente adicionou uma barra lateral ao navegador Chrome, ele criou uma API sidePanel completamente nova. No final de 2025, o Firefox não implementou a API sidePanel e o Safari não adicionou nenhuma delas.
O namespace é outra diferença importante entre WebExtensions e extensões regulares do Chrome. Na API de extensão do Chromium, a maioria das funções começa com “chrome”, como chrome.storage ou chrome.windows. Na maior parte da documentação para WebExtensions, você verá o namespace “navegador”, como browser.storage.
// Showing a welcome page in Chrome’s default API namespace chrome.tabs.create({ 'url': chrome.runtime.getURL('welcome.html') }); // Showing a welcome page in WebExtension ‘browser’ namespace browswer.tabs.create({ 'url': chrome.runtime.getURL('welcome.html') });O Firefox e o Safari suportam “chrome” como um alias para “navegador” para todas as APIs originadas do Chrome, mas o Chrome não reconhece o namespace do navegador.
Fazendo extensões entre navegadores
As práticas recomendadas para desenvolvimento web entre navegadores também se aplicam às extensões. Você precisa testar sua extensão em todo navegador que você deseja oferecer suporte – você quase certamente descobrirá que alguns recursos não funcionam da mesma forma em todos os navegadores.
Você poderia criar um conjunto de testes para ser executado em cada navegador e, idealmente, verificá-lo algumas vezes durante o processo de desenvolvimento. Ao encontrar uma incompatibilidade, use a detecção de recursos para alterar o comportamento, e não a detecção do navegador.
// Example scenario: Chrome has a chrome.bubble extension API, but it’s not yet in Firefox, and we’re using the chrome namespace // This could be checked with feature detection: if ("bubble" in chrome) { console.log("API is available!"); } else { console.error("API is not available!"); } // Do NOT do a browser check like this: if (navigator.userAgent.includes("Firefox")) { console.error("API is not available!"); } else { console.log("API is available!"); }A boa notícia é que a maioria dos navegadores convencionais estão disponíveis nos mesmos sistemas operacionais (Windows, macOS e Linux para desktop), portanto, instalar vários navegadores para testes de extensão não custa nada, exceto espaço de armazenamento. A principal exceção é o Safari, que requer um Mac com Xcode para desenvolvimento de extensões.
Conforme mencionado anteriormente, você também precisará escolher qual namespace deseja usar em seu código: cromo (por exemplo, chrome.storage) ou navegador (por exemplo, navegador.storage). Pessoalmente, limito-me ao namespace chrome, mas você também pode usar a biblioteca polyfill da Mozilla para adicionar suporte ao namespace do navegador ao Chrome. Alguns projetos como o uBlock Origin criam seu próprio wrapper em torno de qualquer namespace disponível.
Para obter recursos atualizados sobre problemas comuns com o desenvolvimento de extensões entre navegadores, verifique a página de incompatibilidades do Chrome do MDN. No final de 2025, a maioria dos problemas eram APIs ou valores de manifesto introduzidos no Manifesto V3.
Quando estiver pronto para publicar sua extensão, lembre-se de que você não ter para usar o repositório de extensões individual de cada navegador. A Chrome Web Store não é apenas para o Chrome – os usuários do Opera, Vivaldi e Edge também podem instalar e atualizar extensões desse site. No entanto, publicar na loja de cada navegador dará mais visibilidade à sua extensão. Por exemplo, o Microsoft Edge direciona seus usuários para o site de complementos do Edge se quiserem baixar extensões, não para a Chrome Web Store. Os usuários do Firefox e Safari não podem instalar extensões diretamente da Chrome Web Store.
O desenvolvimento de extensões entre navegadores não é tão simples quanto pode parecer na documentação do WebExtensions, mas também não é difícil. Muitas extensões de navegador exigirão apenas pequenas alterações no manifesto e na base de código para funcionar em vários navegadores, e a publicação no repositório de extensões de cada navegador não é estritamente necessária. A principal desvantagem é apenas o tempo adicional de teste, porque você não pode fazer as mesmas suposições com compatibilidade entre navegadores que acontece com sites e (a maioria) dos aplicativos da web.