Error Tracking

Collect and monitor errors from your frontend and backend applications.

Overview

Clienwork's error tracking helps you:

• Automatically capture JavaScript errors from your frontend
• Collect server-side errors from your backend
• Track which users encounter errors
• Get Slack notifications for new errors
• View original source code with source maps

Enable Error Collection

1. Go to Project → Settings → Errors
2. Toggle Enable error collection
3. Click Generate Token to create your API token
4. Copy the token for SDK setup

Quick Start

Automatic Setup (Recommended)

Run the setup wizard to automatically configure your project:

npm install @clienwork/errors
npx @clienwork/errors init

The wizard will:

• Detect your project type (Next.js, React, Express, Node.js)
• Automatically configure the necessary files
• Guide you through setting up your API token

---

Next.js Setup

1. Install

npm install @clienwork/errors

2. Set environment variable

# .env.local
NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN=clw_err_xxx

3. Add to next.config.js

const { withClienworkErrors } = require('@clienwork/errors/nextjs')

module.exports = withClienworkErrors({
  // your existing config
})

Done! Errors are now automatically collected.

---

Other Projects (React, Vite, etc.)

1. Install

npm install @clienwork/errors

2. Set environment variable

# .env or .env.local
NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN=clw_err_xxx

3. Import once at app startup

// Add to your main entry file (e.g., main.ts, index.ts)
import '@clienwork/errors/auto'

Done! Errors are now automatically collected.

---

Advanced Usage

Manual Error Reporting

import { report } from '@clienwork/errors'

try {
  // Risky operation
} catch (error) {
  report(error, { context: 'checkout' })
}

User Identification

Track which user encountered each error:

import { setUser, clearUser } from '@clienwork/errors'

// After user login
setUser('user-123') // or user email, UUID, etc.

// After user logout
clearUser()

When a user reports an issue, you can look up all errors for that specific user.

React Error Boundary

Wrap your app with the error boundary component:

import { ClienworkErrorBoundary } from '@clienwork/errors/react'

function App() {
  return (
    <ClienworkErrorBoundary fallback={<ErrorPage />}>
      <MyApp />
    </ClienworkErrorBoundary>
  )
}

Manual Initialization

For full control over initialization:

import { init } from '@clienwork/errors'

init({
  apiToken: process.env.NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN!,
  source: 'frontend',
  release: process.env.NEXT_PUBLIC_APP_VERSION,
  enabled: process.env.NODE_ENV === 'production',
  beforeSend: (error) => {
    // Return null to filter out this error
    return error
  },
})

Backend Setup (Node.js)

Basic Usage

import { createBackendReporter } from '@clienwork/errors'

const errorReporter = createBackendReporter({
  apiToken: process.env.CLIENWORK_ERROR_TOKEN!,
})

try {
  // your code
} catch (error) {
  await errorReporter.report(error, { endpoint: '/api/users' })
  throw error
}

Express Middleware

import { createBackendReporter, expressErrorHandler } from '@clienwork/errors'

const errorReporter = createBackendReporter({
  apiToken: process.env.CLIENWORK_ERROR_TOKEN!,
})

// Add as error middleware
app.use(expressErrorHandler(errorReporter))

Source Maps

Show original source code in stack traces instead of minified code.

Add Version to Environment

# .env.local
NEXT_PUBLIC_APP_VERSION=v1.0.0

Upload After Build

{
  "scripts": {
    "build": "next build",
    "postbuild": "clienwork-upload-sourcemaps --release $NEXT_PUBLIC_APP_VERSION"
  }
}

Or manually:

npx clienwork-upload-sourcemaps \
  --release v1.0.0 \
  --include ".next/**/*.map"

Slack Notifications

Get notified when new errors occur:

1. Go to Project → Settings → Errors
2. Enable Slack notifications
3. Ensure Slack integration is configured

Viewing Error Logs

Access error logs from:

• Workspace → Errors - All errors across projects
• Filter by project, source (frontend/backend), and date range
• Click any error to see full stack trace and metadata

API Alternative (Without SDK)

If you prefer not to use the npm package:

Frontend (Browser)

window.onerror = function(message, source, lineno, colno, error) {
  fetch('https://app.clienwork.com/api/errors', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${ERROR_TOKEN}`
    },
    body: JSON.stringify({
      message: message,
      stack: error?.stack,
      url: window.location.href,
      userAgent: navigator.userAgent,
      source: 'frontend'
    })
  }).catch(() => {})
}

Backend (Node.js)

async function reportError(error, context = {}) {
  await fetch('https://app.clienwork.com/api/errors', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.CLIENWORK_ERROR_TOKEN}`
    },
    body: JSON.stringify({
      message: error.message,
      stack: error.stack,
      source: 'backend',
      metadata: context
    })
  }).catch(() => {})
}