tessl/npm-sentry--integrations

Pluggable integrations that enhance Sentry JavaScript SDKs with additional error tracking, monitoring, and debugging capabilities.

—

Pending

Overview

Eval results

Files

Context Lines

Name: tessl/npm-sentry--integrations
Author: tessl

Browser-only integration that adds source context lines to stack frames pointing to inline JavaScript code in HTML pages. This integration helps debug errors in inline scripts that cannot be accessed by Sentry's backend for context collection.

Capabilities

Modern Function-based Integration

/**
 * Collects source context lines for inline JavaScript in HTML pages
 * @param options - Configuration for context line collection
 * @returns Integration instance that adds context to frames
 */
function contextLinesIntegration(options?: ContextLinesOptions): Integration;

interface ContextLinesOptions {
  /** Number of context lines for each frame. Defaults to 7. Set to 0 to disable. */
  frameContextLines?: number;
}

Legacy Class-based Integration (Deprecated)

/**
 * Legacy class-based context lines integration
 * @deprecated Use contextLinesIntegration() instead
 */
class ContextLines implements Integration {
  constructor(options?: { frameContextLines?: number });
  name: string;
  processEvent(event: Event): Event;
}

Configuration Options

frameContextLines Option

Controls the number of source lines to include around each frame:

Default: 7 lines (3 before + target line + 3 after)
Disable: 0 (no context collection)
Custom: Any positive number for more/less context

Behavior

Target Frames

Only processes stack frames that point to:

Current HTML page: Frame filename matches current page URL
Inline JavaScript: Code embedded directly in HTML (not external JS files)
Valid line numbers: Frames with line number information

Context Collection

The integration:

Extracts complete HTML source from document.documentElement.innerHTML
Converts to line array with DOCTYPE and html tags
Maps stack frame line numbers to HTML lines
Adds surrounding context lines to matching frames

Browser Environment Only

This integration:

Requires DOM: Must have access to document and window
Current page only: Only works for the currently loaded HTML page
No external files: Cannot process external JavaScript files

Usage Examples

import { contextLinesIntegration } from '@sentry/integrations';
import * as Sentry from '@sentry/browser';

// Default 7 lines of context
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    contextLinesIntegration()
  ]
});

// More context lines for better debugging
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    contextLinesIntegration({
      frameContextLines: 15
    })
  ]
});

// Minimal context for performance
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    contextLinesIntegration({
      frameContextLines: 3
    })
  ]
});

// Disable context collection
Sentry.init({
  dsn: 'YOUR_DSN',
  integrations: [
    contextLinesIntegration({
      frameContextLines: 0
    })
  ]
});

HTML Source Processing

The integration reconstructs the HTML document structure:

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <script>
      function buggyFunction() {
        throw new Error('Inline script error');  // Line gets context
      }
      buggyFunction();
    </script>
  </body>
</html>

When an error occurs in the inline script, the integration adds context lines showing the surrounding HTML and JavaScript code.

Exported Test Utilities

/**
 * Applies source context to a single frame (exported for testing)
 * @param frame - Stack frame to process
 * @param htmlLines - Array of HTML source lines
 * @param htmlFilename - Current page filename
 * @param linesOfContext - Number of context lines to include
 * @returns Frame with added context
 */
function applySourceContextToFrame(
  frame: StackFrame,
  htmlLines: string[],
  htmlFilename: string,
  linesOfContext: number
): StackFrame;

Use Cases

This integration is particularly valuable for:

Single Page Applications: SPAs with significant inline JavaScript
Dynamic HTML: Applications generating HTML with embedded scripts
Login-protected pages: Pages Sentry backend cannot access for context
Development debugging: Enhanced local debugging of inline scripts
Legacy applications: Apps with mixed inline/external JavaScript

Limitations

External JS files: Cannot process external JavaScript files (handled by backend)
Cross-origin restrictions: Limited by browser same-origin policies
Performance impact: Processes entire HTML source for each error
Browser only: Not available in Node.js or server-side environments

This integration complements Sentry's backend context collection by handling the specific case of inline JavaScript that cannot be accessed remotely.

Install with Tessl CLI

npx tessl i tessl/npm-sentry--integrations

docs

console-capture.md

context-lines.md

debug-integration.md

error-deduplication.md

reporting-observer.md

session-timing.md

transaction-integration.md

tile.json