@errorgap/nuxt

@errorgap/nuxt

Nuxt module for Errorgap. It reports both client (browser / Vue) and server (Nitro) errors to your Errorgap project, wiring @errorgap/browser and @errorgap/node into Nuxt's plugin and Nitro hooks.

Works with Nuxt 3+.

Install

npm install @errorgap/nuxt

Configure

Add the module and your project settings to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ["@errorgap/nuxt"],
  errorgap: {
    endpoint: "https://errorgap.example.com",
    projectSlug: "my-project",
    // Ingestion-only key. It can submit notices but not read data, so — like a
    // Sentry DSN — it is included in the client bundle for browser reporting.
    apiKey: process.env.ERRORGAP_API_KEY,
    environment: process.env.NODE_ENV,
    release: process.env.NUXT_APP_VERSION,
  },
});

Connection settings can also be provided through runtimeConfig (handy for per-environment secrets):

export default defineNuxtConfig({
  modules: ["@errorgap/nuxt"],
  runtimeConfig: {
    errorgap: { apiKey: "" }, // NUXT_ERRORGAP_API_KEY
    public: {
      errorgap: { endpoint: "", projectSlug: "" }, // NUXT_PUBLIC_ERRORGAP_*
    },
  },
});

Once configured, the module automatically reports:

• Client: Vue render/lifecycle errors (vue:error), fatal app errors (app:error), and — via @errorgap/browser — uncaught window errors and unhandled promise rejections, with source-map-resolved stack traces.
• Server: every unhandled Nitro request error, with the request method and path as context.

Options

Noise, duplicates and ignored environments

errorgap: {
  ignoreEnvironments: ["test"],
  ignoreStatusCodes: [404, 410], // default: every 4xx; [] reports them all
  ignoreNoise: true,      // browser: drop Script error., extension errors, ResizeObserver notices
  dedupeWindowMs: 1000,   // browser: an identical error at most once a second
}

With @errorgap/browser 0.6 and @errorgap/node 0.5 the module also retries failed sends, stops sending for the server's Retry-After after a 429, masks filter keys at any depth and reports cause chains. The server release defaults to ERRORGAP_RELEASE, the hosting platform's commit variable or the git checkout. Uncaught server errors are reported and the exit is left to Nitro.

Browser performance

export default defineNuxtConfig({
  modules: ["@errorgap/nuxt"],
  errorgap: {
    // …connection options…
    performance: { sampleRate: 0.25 },
  },
});

Measures page loads, client-side navigations, Core Web Vitals and fetch/XHR calls (Errorgap → Performance → Browser). Timings are grouped by the matched route pattern (/orders/:id), not the URL.

Session replay

The browser records session replay (shown on error groups and incidents in Errorgap): a timeline of page loads, route changes, failed API calls, errors and rage clicks, plus masked page snapshots. Whether a session is recorded follows the project's settings in Errorgap (Settings → Session replay). Snapshots blank every form field; mark anything else to keep out with data-errorgap-block (removed) or data-errorgap-mask (text masked). See @errorgap/browser.

Manual reporting

<script setup lang="ts">
const errorgap = useErrorgap();

async function save() {
  try {
    await risky();
  } catch (error) {
    await errorgap.notify(error, { context: { component: "SaveButton" } });
  }
}
</script>

useErrorgap().notify works in both client and server contexts.

License

MIT.