Back to Home

Quickstart Guide

Get up and running with Vibesignals in under 2 minutes

1

Install the package

Terminal
bash
npm install @vibesignals/observe

Or use yarn: yarn add @vibesignals/observe

2

Initialize in your entry file

Select your framework to see the correct setup:

app/layout.tsx
typescript
// Add at the very top of your layout file
import { observe } from '@vibesignals/observe';

// Initialize on client side only
if (typeof window !== 'undefined') {
  observe.init('YOUR_API_KEY');
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Note: For Next.js, wrap the init in a browser check to avoid SSR issues.

✓

You're done!

That's it! The SDK now automatically captures:

🔴

Errors

Unhandled exceptions, promise rejections

🌐

HTTP Requests

All fetch/XHR with timing & status

📝

Console Logs

log, warn, and error calls

⚡

Web Vitals

LCP, FID, CLS, TTFB metrics

Configuration Options

Customize the SDK behavior with these options:

Configuration
typescript
observe.init('YOUR_API_KEY', {
  // Environment
  environment: 'production',  // 'development', 'staging', 'production'
  release: '1.0.0',           // Your app version

  // Auto-instrumentation
  captureConsole: true,       // Capture console.log/warn/error
  captureErrors: true,        // Capture unhandled errors
  captureHttp: true,          // Capture fetch/XHR requests
  capturePerformance: true,   // Capture Web Vitals

  // Sampling
  sampleRate: 1.0,            // 1.0 = 100% of events

  // Privacy
  privacy: {
    maskEmails: true,         // user@example.com → u***@example.com
    maskIPs: true,            // 192.168.1.1 → 192.168.*.*
    sensitiveKeys: ['password', 'token', 'apiKey'],
  },

  // Development mode
  dev: false,                 // Set to true to log events instead of sending
});

Track Custom Events

Beyond auto-capture, track business-specific events and metrics:

Custom Events
typescript
import { observe } from '@vibesignals/observe';

// Track custom events
observe.event('user.signup', {
  plan: 'premium',
  referrer: 'google'
});

// Track metrics
observe.metric('checkout.value', 149.99, {
  currency: 'USD',
  items: 3
});

// Trace async operations
await observe.trace('api.call', async () => {
  const response = await fetch('/api/data');
  return response.json();
});

// Manual spans for complex operations
const span = observe.startSpan('database.query');
span.setTag('table', 'users');
await db.query('SELECT * FROM users');
span.finish();

User Context

Associate events with user information for better debugging:

User Context
typescript
import { observe } from '@vibesignals/observe';

// Set user context (after login)
observe.setUser({
  id: 'user_123',
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium'
});

// Set custom context
observe.setContext('cart', {
  items: 3,
  total: 149.99
});

// Clear context (on logout)
observe.clearContext();

Development Mode

Enable dev mode to see what's being tracked without sending data:

Development Mode
typescript
observe.init('YOUR_API_KEY', { dev: true });

// Console output:
// [Vibesignals] HTTP { method: 'GET', url: '/api/users', duration: 145 }
// [Vibesignals] ERROR { message: 'Database connection failed' }

API Reference

MethodDescription
observe.init(apiKey, options?)Initialize the SDK
observe.event(name, data?)Track a custom event
observe.metric(name, value, tags?)Track a metric
observe.trace(name, fn, context?)Trace async function execution
observe.startSpan(name)Start a manual span
observe.setUser(user)Set user context
observe.setContext(key, value)Set custom context
observe.clearContext()Clear all context

Need more help?

Use AI to install automatically or check out the GitHub repo

Install with AIGitHub