Guia de exceptions

Capture erros do browser e do seu servidor em Next.js, Vue/Nuxt e TanStack.

Client

Criar o client já instala os handlers globais, então erros não tratados e promises rejeitadas são capturados sozinhos. Falta ligar os error boundaries do framework, que engolem o erro antes de ele chegar no window.

app/error.tsx

"use client";

import { useEffect } from "react";

import { dataxamas } from "@/lib/dataxamas.client";

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    dataxamas.exceptions.captureException(error, { digest: error.digest });
  }, [error]);

  return (
    <div>
      <h2>Something went wrong</h2>

      <button type="button" onClick={reset}>
        Try again
      </button>
    </div>
  );
}

app/global-error.tsx

"use client";

import { useEffect } from "react";

import { dataxamas } from "@/lib/dataxamas.client";

// Catches errors thrown by the root layout itself, where app/error.tsx cannot run.
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    dataxamas.exceptions.captureException(error, { digest: error.digest, boundary: "global" });
  }, [error]);

  return (
    <html lang="en">
      <body>Something went wrong</body>
    </html>
  );
}

new Dataxamas(...) chama exceptions.install() sozinho, escutando window error e unhandledrejection. Passe captureGlobalErrors: false se preferir instalar na mão.

Error boundaries do React, o errorHandler do Vue e o errorComponent do TanStack capturam erros de render, então eles nunca chegam no handler global — capture na mão como nos exemplos acima.

O mesmo token dx_live_ dos logs também grava erros e, no browser, acaba no bundle público. Para mantê-lo no servidor, repita a rota proxy do guia de Logs chamando exceptions.captureException no lugar dos logs: Logs.

Servidor

No Node os handlers globais escutam process uncaughtException e unhandledRejection. O source é marcado como SERVER automaticamente, e environment e release vêm das opções do client.

instrumentation.ts

import { dataxamas } from "@/lib/dataxamas.server";

// Next.js calls this for every uncaught error in Server Components,
// Route Handlers and Server Actions.
export function onRequestError(
  error: unknown,
  request: { path: string; method: string },
  context: { routerKind: string; routeType: string },
) {
  dataxamas.exceptions.captureException(error, {
    path: request.path,
    method: request.method,
    routeType: context.routeType,
  });
}

// Imported once at boot so the process-level handlers are installed.
export async function register() {
  await import("@/lib/dataxamas.server");
}

app/api/checkout/route.ts

import { dataxamas } from "@/lib/dataxamas.server";

export async function POST(request: Request) {
  try {
    return Response.json(await createOrder(await request.json()));
  } catch (error) {
    await dataxamas.exceptions.captureException(error, { route: "/api/checkout" });

    return Response.json({ error: "Checkout failed" }, { status: 500 });
  }
}

Uma SPA Vue pura e um app TanStack Router puro não têm runtime de servidor — capture pelo seu próprio backend com o mesmo client em escopo de módulo.

Notas

lib/dataxamas.server.ts

import { Dataxamas } from "dataxamas";

export const dataxamas = new Dataxamas({
  token: process.env.DATAXAMAS_TOKEN as string,
  websiteId: process.env.DATAXAMAS_WEBSITE_ID as string,
  captureGlobalErrors: false,
});

// Install them yourself, whenever it suits your boot order.
dataxamas.exceptions.install();

install() é idempotente e vira no-op quando enableErrorTracking é false.
captureException aceita Error, string ou qualquer valor — é normalizado para { name, message, stack }. No browser também anexa url e userAgent.
Toda captura é um POST em /api/v1/errors com Authorization: Bearer <token>.

Referência completa dos métodos: DataxamasExceptions.

AnteriorLogs PróximoDataxamas