JavaScript Errors

JavaScript error tracking captures client-side errors and reports them through your own application. When enabled, the package registers a POST route at /ranetrace/js-errors (named ranetrace.javascript-errors.store, throttled to 60 requests per minute) and exposes a Blade directive that renders the client-side script.

Add the Blade directive

Place @ranetraceErrorTracking in your layout (commonly before </body>). This is code, so it deploys with your app:

<!DOCTYPE html>
<html>
<body>
    @yield('content')

    @ranetraceErrorTracking
</body>
</html>

The directive renders the ranetrace::error-tracker view. When javascript_errors.enabled is false, the directive renders nothing, so it is safe to leave in place even before the feature is on.

Turn it on in production

JavaScript error tracking runs where your users are, so enable it in your production environment, not just a local .env:

RANETRACE_ENABLED=true
RANETRACE_JAVASCRIPT_ERRORS_ENABLED=true

To try it during development, set the same flags in your local .env.

What the script captures

From resources/views/error-tracker.blade.php:

  • window.onerror — uncaught exceptions.
  • unhandledrejection — unhandled promise rejections.
  • Console errors — only when RANETRACE_JAVASCRIPT_CAPTURE_CONSOLE_ERRORS=true (default: false).

It also collects breadcrumbs leading up to the error:

Category Tracked events
navigation Page loaded
user Clicks (tag, id, class, first 50 chars of text), form submissions (action, method)
http XHR completed/failed, fetch completed/failed

The number of breadcrumbs kept is capped at max_breadcrumbs (default: 20).

Sampling and deduplication

  • Sample rate — RANETRACE_JAVASCRIPT_ERRORS_SAMPLE_RATE (default 1.0 = 100%).
  • Deduplication — the script keys errors by message|filename|line|column and skips duplicates within a 50-entry rolling cache.

Ignored errors

config/ranetrace.php ships with a default ignored_errors list, including:

  • ResizeObserver loop limit exceeded / …undelivered notifications
  • Script error. / Script error (cross-origin)
  • Failed to fetch, NetworkError when attempting to fetch resource, Network request failed, Load failed
  • Loading chunk, ChunkLoadError
  • cancelled, canceled, The operation was aborted, AbortError
  • Illegal invocation

Matches are case-insensitive substring checks. Add patterns by publishing the config and extending the array.

Reporting errors manually

The script exposes two helpers on window.Ranetrace:

try {
    riskyOperation();
} catch (error) {
    window.Ranetrace.captureError(error, { payment_amount: amount });
}

window.Ranetrace.addBreadcrumb('user', 'Clicked retry', { attempt: 2 });

captureError(error, context) sends an error immediately. addBreadcrumb(category, message, data) records a breadcrumb for inclusion with the next error.

Testing your setup

php artisan ranetrace:test-javascript-errors

Disabling

RANETRACE_JAVASCRIPT_ERRORS_ENABLED=false

The Blade directive is safe to leave in your layout — it becomes a no-op when the feature is disabled.

On this page