Como criar uma Extensão Pomodoro Chrome com React e TypeScript
A desenvolver do zero uma extensão Pomodoro para o Google Chrome usando React, TypeScript, Tailwind e React Router. Conheça todos os detalhes, desde configuração até salvamento de dados
Por que isso é importante
Extensão Chrome + React: permissions mínimas — pedir tudo é rejeição anunciada.
Leitura relacionada: Curso Next.js · Curso React · shadcn tutorial · Cursos CrazyStack.
Seis Segundos para Provar: O que faz uma boa extensão?
A diferença entre uma extensão ignorada e uma ferramenta diária está em detalhes
invisíveis: salvar dados, ser leve, avisar na hora, funcionar igual em qualquer
dispositivo. Se você quer entender como criar algo realmente útil, cada bloco da
arquitetura conta.
Projeto na Prática: comece simples, pense grande
Tudo começou com o básico: um timer Pomodoro, interface clara, tempo ajustável de foco e
pausa. Mas bastidores contam mais — React, TypeScript, Vite e Tailwind criaram a base e
permitiram agregar funções importantes: som, notificações e sincronização automática.
Manifest.json v3: o coração da extensão
Atenção
Extensões não rodam em servidor! Toda navegação precisa ser baseada em hash, usando o
Hash Router do React Router, ou você perderá as rotas em produção.
O arquivo manifest.json define tudo: permissões, aparência, painéis, ícones e áudio.
Aqui a versão V3 garante uso do side panel, permissões para armazenamento e
notificações, e permite ativar scripts de background via Service Worker.
Configuração do Vite e dois pontos de entrada
O projeto requer dois pontos principais: o index.html da interface e um index.ts
exclusivo para o background (Service Worker). A configuração do Vite precisa garantir
caminhos certos e garantir que o background.js tenha o nome exato, incluindo a
propriedade base para não quebrar referências nos assets da extensão.
Info Técnica
Falhar ao apontar corretamente o entry dos scripts faz com que notificações ou
sincronização simplesmente parem de funcionar. Atenção à padronização dos nomes!
Salvamento Automático: o poder do chrome.storage.sync
O arquivo config-manager.ts centraliza toda a lógica de persistência. Com
chrome.storage.sync, qualquer configuração salva é sincronizada nos Chromes do usuário,
independente do computador — seguro, transparente e sem precisar de back-end.
Notificações ao Estilo Profissional: NotificationManager & Background Service
Como notificações nativas exigem permissão extra, você precisa de uma arquitetura com um
gerenciador que envia mensagens do React para o script de background via
chrome.runtime.sendMessage. Só o background pode disparar alertas no sistema. O ciclo
inteiro é automatizado — ao encerrar foco, mostra a notificação certa, remove depois de
segundos, tudo organizado.
Atenção
Notificações só aparecem se o usuário permitiu. Teste sempre com extensões instaladas
no modo desenvolvedor para validar o fluxo!
O Hook UsePomodoro: tempo, notificações e alternância automática
UsePomodoro encapsula todo o ciclo: tempo em segundos, estado do timer e alternância
entre foco/pausa. Usa useEffect com setInterval e switch interno para trocar
automaticamente o modo, tocar o som e chamar notificações. O áudio é sempre tratado em
try/catch para não travar caso o navegador bloqueie autoplay.
Componentes Reutilizáveis e Interface focada
Três componentes essenciais dão vida e leveza: Button estilizado com Tailwind, Input com
label visível e Icon para renderização dinâmica de símbolos. Interface direta, sem
distrações, toda adaptada ao painel lateral do Chrome — foco total na usabilidade
Pomodoro.
Navegação sem dor de cabeça: Router próprio para extensões
Reforce: HashRouter é obrigatório em extensões Chrome! Ele permite duas páginas
clássicas: Home (timer, controles, título dinâmico) e Config (ajuste dos minutos).
Transições suaves e sem recarregamento, salvando automaticamente as alterações na volta
para a Home.
Dica
Para garantir navegação segura e sem erros, evite manipulação direta do
window.location. Sempre use componentes de navegação do React Router.
Background Script: controle discreto, integração total
O script index.ts do background faz dois papéis: abre o painel lateral ao clicar na
extensão e exibe notificações do sistema recebidas da interface. Tudo isso rodando
isolado, escutando eventos e mantendo a experiência consistente e automatizada em
qualquer fluxo de uso.
Instale local, teste tudo — zero dependência de backend
Após build no React, acesse chrome://extensions — ative modo desenvolvedor, carregue a
pasta dist, abra a extensão. Daí é só ajustar tempos, iniciar o Pomodoro, e ver som,
notificações e salvamento funcionando. Rápido, local e prático.
Atenção Final
Qualquer alteração em arquivos da extensão precisa de reload manual no Chrome. Não
esqueça de atualizar para testar novas versões!
Referência Completa no Repositório
O código-fonte com toda a estrutura está disponível no repositório do projeto (confira
na seção de comentários). Abra, estude cada parte, e modifique para criar novas
extensões conforme sua necessidade.
Avance: o que você adicionaria?
Toda extensão nasce de uma ideia simples, mas cresce junto do seu repertório técnico —
analytics, temas, integração com calendário, diferentes sons. Com essa base, você pode
executar qualquer ideia para resolver um problema real.
Performance e Escalabilidade: escolha certa de stack
Com React, TypeScript, Vite e Tailwind, você conquista interface reativa, organização,
build rápido e fácil manutenção. Todos esses recursos garantem leveza instantânea — e,
se hospedagem for necessário para APIs ou integrações, existem VPS otimizadas para Node
e automações como N8n.
Parceria Especial
Infraestrutura robusta é essencial para projetos em produção. Com servidores
performáticos e suporte nacional, é possível lançar MVPs, automações e webapps de
forma segura, rápida e econômica.
Este conteúdo tem apoio de empresas que investem de verdade no ecossistema dev nacional.
Quer testar? Link e cupom exclusivo disponíveis — aproveite oportunidade de começar com
desconto e performance para seu próximo grande projeto.
Próximo Passo: crie, publique, compartilhe!
Depois de testar a extensão no Chrome, experimente modificar, publicar sua própria
versão e compartilhar no repositório da comunidade. Você pode ir além — adapte para
Firefox, agregue feedback e itere rápido.
Erro Comum
Cuidado para não subir a versão errada ou sem permissão de notificações ativada, pois
alguns recursos dependem dessas permissões explícitas no manifest.
Saia do básico: aprenda em vídeo e avance mais
Quer ver o passo a passo prático, com código aberto e explicação detalhada? Busque o
tutorial em vídeo “Como criar extensão Pomodoro Chrome com React” no canal Dev Doido.
Inscreva-se para acompanhar novos conteúdos e dicas avançadas de desenvolvimento web.
Resumo para quem quer começar agora
Crie sua primeira extensão moderna, focada, sincronizada e responsável por elevar sua
produtividade e seu portfólio técnico. Use este guia como manual prático — cada detalhe
aqui encurta sua curva de aprendizado!
Perguntas frequentes
Extensão Chrome com React: o básico?
Manifest, permissions mínimas e build. Não peça permissões demais.
Pomodoro como exemplo?
Bom para aprender messaging/storage.
React 19?
Confira bundler da extensão.
Publicar?
Review da loja importa.
Continue explorando
Continue: Curso Next.js · Curso React · shadcn tutorial · Cursos CrazyStack.
Perguntas frequentes
Extensão Chrome com React: o básico?
Manifest, permissions mínimas e build. Não peça permissões demais.
Pomodoro como exemplo?
Bom para aprender messaging/storage.
React 19?
Confira bundler da extensão.
Publicar?
Review da loja importa.
Seis Segundos para Provar: O que faz uma boa extensão?
A diferença entre uma extensão ignorada e uma ferramenta diária está em detalhes invisíveis: salvar dados, ser leve, avisar na hora, funcionar igual em qualquer dispositivo. Se você quer entender como criar algo realmente útil, cada bloco da arquitetura conta.
Avance: o que você adicionaria?
Toda extensão nasce de uma ideia simples, mas cresce junto do seu repertório técnico — analytics, temas, integração com calendário, diferentes sons. Com essa base, você pode executar qualquer ideia para resolver um problema real.