Monitoramento de Erros com Sentry no React + Vite: Guia Completo

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: {data.length > 0 && ( )} // erro proposital { throw new Error("This is your first error!"); }} > Break the world 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 } })

May 8, 2025 - 23:14

Monitoramento de Erros com Sentry no React + Vite: Guia Completo

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?