@drilonhametaj/observer-nextjs

The cuore of the Observer SDK. Embeds an ingest API, a deterministic classification pipeline, typed prompt templates, and a /error-analytics dashboard inside any Next.js host app.

No central service. Every host app stores its own incidents in its own Postgres. The dashboard lives at /error-analytics inside the host. Tables are prefixed observer_*.

Status: alpha. Only safe to use in dev environments.

Install

pnpm add @drilonhametaj/observer-nextjs \
  typeorm pg bullmq ioredis resend source-map

You also need:

• Postgres 15+ (the host's database)
• Redis 7+ (BullMQ pipeline)

5-minute integration

1. Configure once

// observer.config.ts
import { configureObserver } from '@drilonhametaj/observer-nextjs'
import { dataSource } from './data-source'

export const observer = configureObserver({
  projectName: 'OLF ERP',
  dataSource,
  redisUrl: process.env.REDIS_URL!,
  apiKey: process.env.OBSERVER_KEY!,
  isAdmin: async (req) => {
    // your existing auth — return true if user can see the dashboard
  },
  notifications: {
    email: process.env.OBSERVER_NOTIFY_EMAIL!,
    resendApiKey: process.env.RESEND_API_KEY!,
  },
})

2. Add Observer's TypeORM entities to your DataSource

import { observerEntities, observerMigrations } from '@drilonhametaj/observer-nextjs/db'

export const dataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  entities: [...myAppEntities, ...observerEntities],
  migrations: [...myAppMigrations, ...observerMigrations],
})

3. Mount the API

// app/api/observer/[...route]/route.ts
export { GET, POST, PATCH } from '@drilonhametaj/observer-nextjs/api'

4. Mount the dashboard

// app/error-analytics/page.tsx
export { InboxPage as default } from '@drilonhametaj/observer-nextjs/pages'

// app/error-analytics/incident/[id]/page.tsx
export { IncidentPage as default } from '@drilonhametaj/observer-nextjs/pages'

5. Run the workers

// scripts/start-workers.ts
import { startObserverWorkers } from '@drilonhametaj/observer-nextjs/workers'
import { observer } from '../observer.config'

startObserverWorkers(observer)

# package.json
"dev": "concurrently 'next dev' 'tsx scripts/start-workers.ts'"

Tailwind requirement

The dashboard ships Tailwind-classed components. Add the package to your Tailwind content glob:

// tailwind.config.ts
content: [
  './app/**/*.{ts,tsx}',
  './node_modules/@drilonhametaj/observer-nextjs/dist/**/*.js',
]

What you get

The classifier deterministically buckets every event into one of 18 categories:

• js_exception, promise_rejection, react_error
• api_error_4xx, api_error_5xx, silent_api_failure, request_timeout
• dead_click, rage_click, form_submit_silent_fail, optimistic_rollback, expectation_unmet
• backend_exception, db_query_error, slow_query, n_plus_one, job_failure
• route_5xx_spike (sliding-window spike detector)
• unknown_pattern (catch-all)

Each category has its own typed Markdown template — when a new incident is created, the worker renders a Claude-Code-ready prompt and saves it to the incident. Copy it from the dashboard, paste into Claude Code, done.

Notifications

Resend integration with throttling: 1 email per fingerprint per day, keyed in Redis with TTL.

Architecture

See ARCHITECTURE.md in the monorepo for the full pipeline + cross-stack correlation diagrams.

License

MIT © Drilon Hametaj