watchup-svelte

SvelteKit SDK for Watchup – capture client-side errors, stack traces, and Svelte component traces, and report them to your Watchup project.

Think of it like a lightweight, Svelte-native error reporter (similar to Sentry), but built specifically for watchup.site.

✨ Features

• ✅ Automatic JavaScript error capture
• ✅ Unhandled promise rejection tracking
• ✅ Svelte component stack traces
• ✅ Manual error reporting
• ✅ Works with SvelteKit (SSR-safe)
• ✅ Minimal, tree-shakeable ESM package
• ✅ Configurable API endpoint

📦 Installation

npm install watchup-svelte

or

pnpm add watchup-svelte

🚀 Quick Start

Initialize Watchup once on the client (usually in +layout.svelte).

<script lang="ts">
  import { initWatchup } from 'watchup-svelte'

  initWatchup({
    projectId: 'your_project_id',
    apiKey: 'your_api_key'
  })
</script>

That’s it. Errors are now automatically reported.

🔐 Authentication

Watchup authenticates requests using HTTP headers:

• X-Watchup-Project → your project ID
• X-Watchup-Key → your API key

The SDK handles this automatically.

🌍 API Endpoint

By default, events are sent to:

https://watchup-server.vercel.app

You can override this (self-hosting, staging, etc.):

initWatchup({
  projectId: 'your_project_id',
  apiKey: 'your_api_key',
  apiUrl: 'https://your-custom-server.com' (OPTIONAL)
})

🧠 What Gets Captured

Each event includes:

• Error message
• Stack trace
• Svelte component stack (when available)
• Page URL
• User agent
• Timestamp (ISO-8601)

This matches Watchup’s /v1/capture API exactly.

✋ Manual Error Capture

You can manually report errors anywhere in your app:

import { captureException } from 'watchup-svelte'

try {
  riskyOperation()
} catch (err) {
  captureException(err)
}

Useful for:

• Caught exceptions
• Custom validation errors
• Non-fatal issues

🧩 Capturing Svelte Component Errors

To capture Svelte component errors with component stack traces, use the provided helper.

<script lang="ts">
  import { watchupErrorHandler } from 'watchup-svelte'

  export let error
  export let componentStack

  if (error) {
    watchupErrorHandler(error, componentStack)
  }
</script>

This maps directly to Watchup’s componentStack field.

⚙️ SvelteKit Error Hooks (Optional)

You can also capture errors thrown from load() or routing logic.

// hooks.client.ts
import { captureException } from 'watchup-svelte'

export function handleError({ error }) {
  captureException(error)
}

🛡️ SSR Safety

• No browser APIs are accessed during SSR
• Error listeners are registered only in the browser
• Safe to import in SvelteKit layouts

🚦 Rate Limiting

Watchup enforces rate limits per project.

• Events are sent in a fire-and-forget manner
• Failed requests are silently ignored
• Errors inside the SDK never crash your app

📚 API Reference

initWatchup(options)

Initializes the Watchup SDK.

initWatchup({
  projectId: string
  apiKey: string
  apiUrl?: string
})

| Option | Required | Description | | ----------- | -------- | ------------------------- | | projectId | ✅ | Watchup project ID | | apiKey | ✅ | Watchup API key | | apiUrl | ❌ | Custom Watchup server URL |

captureException(error, componentStack?)

Manually report an error.

captureException(error)
captureException(error, 'Component.svelte > Child.svelte')

watchupErrorHandler(error, componentStack)

Helper for Svelte component error boundaries.

🧪 Development Tips

• Initialize only once (usually in root layout)
• Avoid calling initWatchup during SSR
• Do not wrap captureException in try/catch

🗺️ Roadmap

• Source map support
• Error deduplication
• Offline queue & retry
• User/session tagging
• Framework SDKs (React, Vue)

📄 License

MIT