@clienwork/errors

Error collection SDK for Clienwork

Automatically collect and monitor errors from your frontend and backend applications. View error logs, analyze stack traces, and receive Slack notifications from the Clienwork dashboard.

Get Started | Documentation | Dashboard

Automatic Setup (Recommended)

Run the setup wizard to automatically configure your project:

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

Quick Start

Option A: Next.js (Recommended)

3 steps to start collecting errors:

1. Install

npm install @clienwork/errors

2. Set environment variable

# .env.local
NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN=clw_err_xxx

Get your token from Project Settings → Error Collection in the Clienwork dashboard

3. Add to next.config.js

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

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

Done! Errors are now automatically collected.

Option B: Auto Import

For any JavaScript/TypeScript project:

1. Install

npm install @clienwork/errors

2. Set environment variable

# .env or .env.local
NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN=clw_err_xxx  # Frontend
CLIENWORK_ERROR_TOKEN=clw_err_xxx              # Backend

3. Import once at app startup

import '@clienwork/errors/auto'

Done! Errors are now automatically collected.

Option C: Manual Setup

For full control over initialization:

import { init } from '@clienwork/errors'

init({
  apiToken: process.env.NEXT_PUBLIC_CLIENWORK_ERROR_TOKEN!,
  source: 'frontend',
})

Advanced Usage

Manual Error Reporting

import { report } from '@clienwork/errors'

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

User Identification

Associate errors with specific users:

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

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

// After user logout
clearUser()

React Error Boundary

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

function App() {
  return (
    <ClienworkErrorBoundary fallback={<div>Something went wrong.</div>}>
      <MyComponent />
    </ClienworkErrorBoundary>
  )
}

useErrorReporter Hook

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

function MyComponent() {
  const { report } = useErrorReporter()

  const handleClick = async () => {
    try {
      await riskyOperation()
    } catch (error) {
      report(error, { action: 'button-click' })
    }
  }

  return <button onClick={handleClick}>Click</button>
}

HOC

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

const SafeComponent = withErrorBoundary(MyComponent, <div>Error occurred</div>)

Backend Usage (Node.js)

Basic Usage

import { createBackendReporter } from '@clienwork/errors'

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

try {
  // Risky operation
} catch (error) {
  await errorReporter.report(error, { endpoint: '/api/users' })
}

Express Middleware

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

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

app.use(expressErrorHandler(errorReporter))

Next.js API Routes

import { createBackendReporter } from '@clienwork/errors'

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

export async function GET(request: Request) {
  try {
    // ...
  } catch (error) {
    await errorReporter.report(error as Error)
    return new Response('Error', { status: 500 })
  }
}

Configuration Options

init({
  apiToken: 'clw_err_xxx',     // Required: API token
  endpoint: 'https://...',     // Optional: Custom endpoint
  source: 'frontend',          // Optional: 'frontend' | 'backend'
  enabled: true,               // Optional: Enable/disable (useful for dev)
  defaultMetadata: {},         // Optional: Default metadata for all errors
  beforeSend: (error) => {     // Optional: Modify/filter before sending
    // Return null to cancel sending
    return error
  },
})

Support

• Clienwork Homepage
• Contact Us
• GitHub Issues

License

MIT - Clienwork