debugfast-js
v1.0.4
Published
Front-end bug catching library for React and Vue applications with comprehensive error context capture
Downloads
162
Maintainers
invokifyReadme
debugfast-js
Front-end error tracking SDK for DebugFast — captures comprehensive error context including screenshots, console logs, network requests, DOM snapshots, and user actions. Works with React, Vue, and Next.js.
Installation
npm install debugfast-js
# or
pnpm add debugfast-js
# or
yarn add debugfast-jsQuick Start
import { DebugFast } from 'debugfast-js';
DebugFast.init({
apiKey: 'your-api-key',
});Events are sent to https://ingestion.debugfa.st/v1/events by default. Set apiEndpoint if you are self-hosting the ingestion API:
DebugFast.init({
apiKey: 'your-api-key',
apiEndpoint: 'https://your-own-backend.com/v1/events',
});Framework Integration
React
import { DebugFastErrorBoundary } from 'debugfast-js/react';
function App() {
return (
<DebugFastErrorBoundary
fallback={<div>Something went wrong</div>}
onError={(error, errorInfo) => console.log(error)}
>
<YourApp />
</DebugFastErrorBoundary>
);
}Or use the higher-order component:
import { withDebugFastErrorBoundary } from 'debugfast-js/react';
const SafeComponent = withDebugFastErrorBoundary(MyComponent, {
fallback: <ErrorFallback />,
});Next.js (App Router)
The SDK uses browser APIs (window, document) and must only run on the client. In Next.js App Router, 'use client' components are still executed on the server during SSR, so a typeof window !== 'undefined' guard is required.
1. Create a providers.tsx client component — initialize the SDK at module level so it starts as early as possible on the client:
// app/providers.tsx
'use client';
import DebugFast from 'debugfast-js';
import { DebugFastErrorBoundary } from 'debugfast-js/react';
if (typeof window !== 'undefined') {
DebugFast.init({
apiKey: 'your-api-key',
});
}
export function Providers({ children }: { children: React.ReactNode }) {
return (
<DebugFastErrorBoundary
fallback={(error, reset) => (
<div>
<p>{error.message}</p>
<button onClick={reset}>Try Again</button>
</div>
)}
>
{children}
</DebugFastErrorBoundary>
);
}2. Wrap your root layout:
// app/layout.tsx
import { Providers } from './providers';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}3. Mark any component that calls DebugFast methods with 'use client':
// app/some-page.tsx
'use client';
import DebugFast from 'debugfast-js';
export function MyComponent() {
const handleClick = () => {
try {
riskyOperation();
} catch (error) {
DebugFast.captureError(error as Error);
}
};
return <button onClick={handleClick}>Do something</button>;
}Vue 3
import { createApp } from 'vue';
import { debugfastPlugin } from 'debugfast-js/vue';
import App from './App.vue';
const app = createApp(App);
app.use(debugfastPlugin, {
captureComponentInfo: true, // Include Vue component props and route info
});
app.mount('#app');Composition API helper:
<script setup>
import { useDebugFastErrorHandler } from 'debugfast-js/vue';
const { captureError } = useDebugFastErrorHandler();
function handleRiskyOperation() {
try {
// risky code
} catch (error) {
captureError(error, { context: 'riskyOperation' });
}
}
</script>Configuration
DebugFast.init({
// Required
apiKey: 'your-api-key',
// Optional — defaults to https://ingestion.debugfa.st/v1/events
// Set this if you are self-hosting the ingestion API
// apiEndpoint: 'https://your-own-backend.com/v1/events',
// Optional - all default to true
captureScreenshot: true,
captureConsole: true,
captureNetwork: true,
captureDom: true,
captureUserActions: true,
// Limits
screenshotQuality: 0.7, // 0-1, default: 0.7
maxConsoleEntries: 50, // default: 50
maxNetworkRequests: 20, // default: 20
maxUserActions: 30, // default: 30
// Privacy
maskSensitiveInputs: true, // Mask password fields, etc.
// Custom context
tags: { environment: 'production' },
user: { id: 'user-123', email: '[email protected]' },
// Hooks
beforeSend: (report) => {
// Modify report or return false to cancel
return report;
},
// Debug
debug: false,
});API Reference
Static Methods
DebugFast.init(config)
Initialize the SDK. Must be called before any other methods.
DebugFast.captureError(error, options?)
Manually capture an error.
try {
await riskyOperation();
} catch (error) {
DebugFast.captureError(error, {
extra: { operationId: '123' },
tags: { severity: 'high' },
});
}DebugFast.setUser(user)
Set or update user information.
DebugFast.setUser({
id: 'user-123',
email: '[email protected]',
name: 'John Doe',
});DebugFast.setTags(tags)
Add custom tags to all future error reports.
DebugFast.setTags({
version: '1.2.3',
feature: 'checkout',
});DebugFast.flush()
Flush any pending error reports. Useful before page unload.
window.addEventListener('beforeunload', () => {
DebugFast.flush();
});DebugFast.destroy()
Clean up and remove all event listeners.
DebugFast.destroy();DebugFast.getInstance()
Get the current DebugFast instance (or null if not initialized).
What Gets Captured
Each error report includes:
| Data | Description | |------|-------------| | Error | Message, name, parsed stack trace | | Screenshot | Visual capture of the page at error time | | Browser | Browser, OS, viewport, device type, URL | | Console | Recent console.log/warn/error entries | | Network | Recent fetch/XHR requests with timing | | User Actions | Recent clicks, inputs, navigation | | DOM | HTML snapshot (sensitive inputs masked) | | User | Custom user identification | | Tags | Custom metadata |
Privacy
- Sensitive inputs (password, credit card, SSN) are automatically masked
- DOM snapshots redact sensitive field values
- Use
beforeSendhook to filter or redact additional data - Screenshot capture can be disabled globally or per-error
Error Sources
Errors are automatically captured from:
window.onerror(global errors)window.onunhandledrejection(unhandled promise rejections)- React Error Boundaries
- Vue error handlers
Browser Support
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
Requires crypto.randomUUID() or falls back to polyfill.
TypeScript
Full TypeScript support with exported types:
import type {
DebugFastConfig,
ErrorReport,
CaptureOptions,
UserInfo,
StackFrame,
BrowserInfo,
} from 'debugfast-js';License
MIT