Lescopr Node.js SDK

Lescopr is a zero-configuration Node.js monitoring SDK that automatically captures logs, errors and exceptions from any JavaScript project and streams them in real-time to the Lescopr app.

Works out of the box with Express, Next.js, NestJS, Fastify, Koa and plain Node.js — zero runtime dependencies.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Framework Integration
  • Express
  • Next.js
  • NestJS
  • Fastify
  • Koa
  • Plain Node.js
• Architecture
• CLI Reference
• Advanced Configuration
• npm
• License

Features

• ✅ Automatic error capture — hooks into uncaughtException, unhandledRejection and process.exit
• ✅ Framework auto-detection — detects Express, Next.js, NestJS, Fastify, Koa, Nuxt, Remix and Astro from package.json
• ✅ Background flush — non-blocking setInterval timer, completely transparent
• ✅ Zero runtime dependencies — only Node.js built-in https, fs, path
• ✅ Works everywhere — Express, Next.js, NestJS, Fastify, Koa, scripts, plain Node.js

Requirements

| Requirement | Version | |---|---| | Node.js | ≥ 16.0.0 | | npm / yarn / pnpm | any recent |

Zero runtime dependencies — https, fs and path are Node.js built-ins.

Installation

npm install lescopr
# or
yarn add lescopr
# or
pnpm add lescopr

Quick Start

Step 1 — Initialise in your project:

npx lescopr init --sdk-key YOUR_SDK_KEY

Step 2 — Add to your application (see Framework Integration).

That's it. All logs, errors and exceptions are forwarded automatically.

Framework Integration

Express

const express = require('express');
const lescopr  = require('lescopr');
const { lescoprMiddleware, lescoprErrorHandler } = require('lescopr/express');

lescopr.init({
  sdkKey:      process.env.LESCOPR_SDK_KEY,
  apiKey:      process.env.LESCOPR_API_KEY,
  environment: process.env.NODE_ENV,
});

const app = express();
app.use(lescoprMiddleware());   // optional request logging

// ... your routes ...

app.use(lescoprErrorHandler()); // ← must be LAST

Next.js

instrumentation.ts (App Router — Next.js 13.4+):

import lescopr from 'lescopr';

export function register() {
  lescopr.init({
    sdkKey:      process.env.LESCOPR_SDK_KEY,
    apiKey:      process.env.LESCOPR_API_KEY,
    environment: process.env.NODE_ENV,
  });
}

API route wrapper (Pages Router):

import { withLescopr } from 'lescopr/nextjs';

export default withLescopr(async function handler(req, res) {
  res.json({ ok: true });
});

NestJS

main.ts:

import { NestFactory } from '@nestjs/core';
import { AppModule }   from './app.module';
import { LescoprFilter } from 'lescopr/nestjs';
import lescopr from 'lescopr';

async function bootstrap() {
  lescopr.init({
    sdkKey:      process.env.LESCOPR_SDK_KEY,
    apiKey:      process.env.LESCOPR_API_KEY,
    environment: process.env.NODE_ENV,
  });

  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new LescoprFilter());
  await app.listen(3000);
}
bootstrap();

Fastify

const fastify = require('fastify')({ logger: true });
const lescopr  = require('lescopr');

lescopr.init({ sdkKey: process.env.LESCOPR_SDK_KEY, apiKey: process.env.LESCOPR_API_KEY });

fastify.register(require('lescopr/fastify'));

Koa

const Koa = require('koa');
const lescopr = require('lescopr');
const { lescoprMiddleware } = require('lescopr/koa');

lescopr.init({ sdkKey: process.env.LESCOPR_SDK_KEY, apiKey: process.env.LESCOPR_API_KEY });

const app = new Koa();
app.use(lescoprMiddleware()); // ← first middleware

Plain Node.js

const http    = require('http');
const lescopr = require('lescopr');
const { wrapServer } = require('lescopr/vanilla');

lescopr.init({ sdkKey: 'lsk_xxx', apiKey: 'lak_xxx' });

const server = wrapServer(http.createServer((req, res) => {
  res.end('Hello!');
}));

server.listen(3000);

Architecture

Your Node.js Application
        │
        │  throw / console / Lescopr.log
        ▼
┌──────────────────────────────────┐
│  Framework Middleware / Filter   │  (Express / Fastify / NestJS / Koa)
│  OR uncaughtException handler    │  (plain Node.js)
└──────────────┬───────────────────┘
               │ push to LogQueue
               ▼
┌──────────────────────────────────┐
│   setInterval flush (5 s)        │  non-blocking, unref'd
│   Batch drain → HttpTransport    │
└──────────────┬───────────────────┘
               │ HTTPS (net/http — built-in)
               ▼
    https://api.lescopr.com
               │
               ▼
     Lescopr App
  https://app.lescopr.com

| Module | Path | Role | |---|---|---| | Entry point | src/index.js | init, log, captureException, reset | | LescoprClient | src/core/client.js | Bootstrap, flush timer, global handlers | | LogQueue | src/core/log-queue.js | In-memory queue, max-size eviction | | HttpTransport | src/transport/http.js | HTTPS batch via https built-in | | ProjectAnalyzer | src/filesystem/project-analyzer.js | Framework detection from package.json | | ConfigManager | src/filesystem/config-manager.js | .lescopr.json read/write | | Express | src/integrations/express/ | Middleware + error handler | | Fastify | src/integrations/fastify/ | Plugin with onError hook | | Koa | src/integrations/koa/ | Async middleware | | Next.js | src/integrations/nextjs/ | withLescopr wrapper | | NestJS | src/integrations/nestjs/ | LescoprFilter exception filter | | CLI | bin/lescopr.js | init, status, diagnose, reset |

CLI Reference

npx lescopr [command] [options]

| Command | Description | |---|---| | init --sdk-key KEY | Initialise SDK, detect framework, write .lescopr.json | | status | Show current configuration | | diagnose | Node version, config, API connectivity | | reset | Remove .lescopr.json and .lescopr.log |

Advanced Configuration

lescopr.init({
  sdkKey:        'lsk_xxx',          // required
  apiKey:        'lak_xxx',          // required
  environment:   'production',       // default: "development"
  debug:         false,              // verbose logging to .lescopr.log
  batchSize:     50,                 // logs per flush
  flushInterval: 5000,               // ms between flushes
});

Environment variables:

| Variable | Description | |---|---| | LESCOPR_SDK_KEY | SDK key | | LESCOPR_API_KEY | API key | | LESCOPR_ENVIRONMENT | development or production | | LESCOPR_DEBUG=true | Verbose output to .lescopr.log |

npm

The package is available on npm: lescopr

npm install lescopr

Support

| Channel | Link | |---|---| | 📖 Documentation | https://lescopr.com/docs | | 🌐 App | https://app.lescopr.com | | 📧 Email | [email protected] | | 🐛 Bug reports | https://github.com/Lescopr/lescopr-js/issues |

License

MIT © 2024-2026 SonnaLab