Se você desenvolve com React + Vite , integrar o Sentry pode ser o passo mais inteligente para garantir observabilidade, rastrear bugs em produção e entender o que está acontecendo com seus usuários — antes que eles reclamem.
Neste artigo, você vai aprender:
- O que é o Sentry e por que usá-lo
- Como integrá-lo em um projeto React + Vite
- Como testar, personalizar e tirar proveito real da ferramenta
- e muitos mais
O que é o Sentry?
O Sentry é uma ferramenta de monitoramento de erros em tempo real. Ele captura exceções, mostra o contexto (usuário, navegação, ambiente) e ainda integra com ferramentas como Slack, GitHub e Jira.
Por que usar Sentry em React?
- Stack trace completo com source maps (achei melhor que Datadog e Dynatrace)
- Captura de erros não tratados e warnings
- Agrupamento inteligente de problemas
- Performance monitoring (opcional)
Se liga no Trace detalhado disso:
No código:
<div className="flex h-screen flex-col bg-white">
<Header />
<div className="flex w-full flex-col items-center">
<Search
setRecord={setRecord}
setId={handlePatient}
selectedPatientId={patientId}
/>
{data.length > 0 && (
<Records data={data as Data} setNextRecord={setNextRecord} />
)}
// erro proposital
<button
onClick={() => {
throw new Error("This is your first error!");
}}
>
Break the world
</button>
</div>
</div>
No Sentry: Um tracing claríssimo de entender (arrochado demais).
Issue Tracing
Passo a passo: Integrando Sentry em um projeto React + Vite
1. Crie uma conta no Sentry
Acesse sentry.io e crie um projeto do tipo React. Em seguida verá uma tela para preencher nome, email, nome da organização (Pode ser seu nome mesmo), Localização do Storage (Coloquei US) e clique em continuar.
Após isso, verá a Tela de boas vindas. Basta clicar no botão START.
Welcome
2. Configuração do SDK
Faça a Seleção da plataforma em questão: REACT
E Configure o React SDK, que fornecerá os comando de instalação e um código de incorporação para colocar no seu código. Eu criei um helperzinho para organizar e separar responsabilidades (S do SOLID mandou lembraças). Mais a frente mostro como ficou o código final.
Obs.: Tracing e Session Replay, por padrão, na configuração, apenas o Error Monitoring vem marcado, mas podemos marcar as duas outras opções de Tracing e Session Replay. O resultado é a imagem abaixo:
Criei a branch sentry-integration para isolar a feature.
git checkout -b sentry-integration
3. Instale o pacote do Sentry no seu projeto
pnpm install @sentry/react
4. Configurar o init
Criei um helper dentro de src/lib/monitoring/sentry.setup.ts
import * as Sentry from "@sentry/react";
// poderia estar em outro canto, inclusive
declare global {
interface ImportMeta {
env: {
VITE_SENTRY_DSN: string;
};
}
}
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
// Setting this option to true will send default PII data to Sentry.
// For example, automatic IP address collection on events
sendDefaultPii: true,
integrations: [
Sentry.browserTracingIntegration(),
Sentry.replayIntegration()
],
// Tracing
tracesSampleRate: 1.0, // Capture 100% of the transactions
// Set 'tracePropagationTargets' to control for which URLs distributed tracing should be enabled
tracePropagationTargets: ["localhost", /^https://yourserver.io/api/],
// Session Replay
replaysSessionSampleRate: 0.1, // This sets the sample rate at 10%. You may want to change it to 100% while in development and then sample at a lower rate in production.
replaysOnErrorSampleRate: 1.0 // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur.
});
Dica: use variável de ambiente (import.meta.env.VITE_SENTRY_DSN) para proteger seu DSN no build.
E importei no main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import "./lib/monitoring/sentry.setup";
ReactDOM.createRoot(document.getElementById('root')!).render(
)
Configurando Source Maps
Um ponto muito importante: Quando você builda seu projeto (com Vite, Webpack, etc), o código JavaScript é:
- Minificado (nomes de variáveis viram a, b, etc)
- Transpilado (de TS para JS, por exemplo)
- Compactado em poucos arquivos
Isso torna os erros ilegíveis no ambiente de produção.
Exemplo de erro sem Source Map:
TypeError: Cannot read properties of undefined (reading 'x')
at a.js:1:3249
Ou seja: você não tem ideia de onde isso aconteceu no seu código-fonte real.
Para que servem os Source Maps no Sentry?
Eles fazem o mapeamento entre o código minificado e o código original. Com isso, o Sentry consegue:
- Mostrar o arquivo original (Ex.: App.tsx, main.tsx)
- Mostrar a linha e coluna exata (senão, bem próxima.rsrs)
- Mostrar variáveis com nomes reais
Como gerar e enviar Source Maps com Vite
- Gere os source maps no build (Vite já faz por padrão):
vite build --sourcemap
Ou no vite.config.ts:
export default defineConfig({
build: {
sourcemap: true
}
})
Ou simplemente execute esse comando abaixo fornecido pelo próprio Sentry, conforme imagem abaixo:
é uma maneira automatizada e simplificada de configurar upload de source maps no seu projeto.
O que ele faz?
Esse comando roda o Sentry Wizard , que:
- Detecta automaticamente seu framework (como Vite, Next.js, React, etc). No caso, identificou que era como Vite e alterou o vite.config.js adicionando o seguinte (tudo que está abaixo do // adiconado pelo Sentry Wizard):
import { sentryVitePlugin } from "@sentry/vite-plugin";
.
.
.
// https://vite.dev/config/
export default defineConfig({
plugins: [react(), tailwindcss(),
// adicionado pelo Sentry Wizard
sentryVitePlugin({
org: "werliton-silva",
project: "javascript-react"
})],
resolve: {
alias: {
// eslint-disable-next-line no-undef
'@': path.resolve(__dirname, './src'),
},
},
// adicionado pelo Sentry Wizard
build: {
sourcemap: true
}
})
- Instala e configura o @sentry/cli
- Adiciona scripts no seu package.json para:
- Criar uma nova versão (release)
- Gerar e enviar os source maps para o Sentry
Segurança
Nunca commite seu SENTRY_AUTH_TOKEN no repositório. Guarde-o em variáveis de ambiente seguras no seu CI/CD (como GitHub Actions, Vercel, etc).
Se você não subir os source maps:
O erro ainda será capturado, mas será difícil entender onde e por que aconteceu, ou seja, você perde quase todo o valor do Sentry.
5. Teste de erro
Inclui o erro proposital para verificar a captura de erros pelo Sentry. Adicionei o código abaixo no App.tsx
...jsx
...
O erro será reportado no painel do Sentry com stack trace, arquivo e linha exata e muitas outras informações. Além disso, ele envia um email te avisando (muito massa!). Daria uns 2 a 3 outros posts. Comenta aqui se quiser ver nos próximos.
Recursos avançados
Captura manual: Pode ser utilizado com o bom e velho try catch
try {
// código
} catch (error) {
Sentry.captureException(error)
}
ou usando a api do Sentry. Por exemplo para captura de mensagem customizada:
Sentry.captureMessage("Botão de compra clicado sem produto selecionado")
ou captura de Informações do usuário:
Sentry.setUser({
id: "123",
email: "usuario@exemplo.com",
username: "usuario123"
})
Claro que tem mais outras opções (vide a bula da documentação).
Monitoramento de performance (opcional)
O BrowserTracing já ativa o monitoramento de rotas, tempo de carregamento, interações, etc. No painel do Sentry, você pode ver em Frontend > Web Vitals:
- Tempo até o primeiro paint (FCP), TTFB, FCP
Boas práticas
- Use release e environment para rastrear erros por versão
- Nunca envie erros em modo de desenvolvimento (process.env.NODE_ENV)
- Combine com alertas no Slack (ou seu app de fofoca preferido) para agir rápido
- Ative source maps no build de produção (Webpack/Vite configurados corretamente já fazem isso)
Conclusão
Adicionar o Sentry ao seu projeto React + Vite é rápido e extremamente valioso. Ele não só te avisa sobre erros, como te mostra o porquê e onde eles aconteceram com contexto real.
Se você quer elevar o nível da sua aplicação e garantir uma experiência fluida para o usuário, essa é uma das integrações mais simples e poderosas que você pode fazer.
Diz aí…
Qual ferramenta de monitoramento você usa hoje? Será que ela entrega tudo isso?
