Flash Analytics Express SDK

Express middleware for automatic request and error tracking.

Install

npm install @flash-analytics/express

Quick Start

import express from 'express';
import createMiddleware, { createErrorMiddleware } from '@flash-analytics/express';

const app = express();

// Track every request automatically
app.use(createMiddleware({
  clientId: 'your-app-id',
  clientSecret: 'your-secret-key',
  endpoint: 'https://api.flashanalytics.app',
}));

app.get('/', (req, res) => {
  res.send('Hello');
});

// Track every unhandled error automatically (must be last)
app.use(createErrorMiddleware({
  clientId: 'your-app-id',
  clientSecret: 'your-secret-key',
  endpoint: 'https://api.flashanalytics.app',
}));

Auto-Tracked Events

| Event | Trigger | |---|---| | request | Every HTTP request (method, URL, status code, duration) | | server_error | Every unhandled error passed to Express error middleware |

Options

type FlashAnalyticsExpressOptions = {
  clientId: string;               // Your Flash Analytics app ID
  clientSecret?: string;          // Secret key for server-to-server calls
  endpoint?: string;              // API base URL (default: https://api.flashanalytics.app)

  // Filter which requests are tracked
  shouldCaptureExpressRequest?: (req: Request) => boolean;

  // Filter which errors are tracked
  shouldCaptureError?: (err: Error, req: Request) => boolean;

  // Resolve a user/profile ID from the request
  resolveUserId?: (req: Request) => string;

  // Debug mode — logs track success/failure to console
  debug?: boolean;

  // Callbacks
  onTrackSuccess?: (eventName: string, response: any) => void;
  onTrackError?: (eventName: string, error: any) => void;
};

Manual tracking via req.fa

The middleware attaches a FlashAnalytics instance to req.fa for manual tracking inside route handlers:

app.post('/checkout', (req, res) => {
  req.fa.track('checkout_started', {
    cartValue: req.body.total,
    itemCount: req.body.items.length,
  });
  res.json({ ok: true });
});

Filter requests

Skip health checks or static assets:

app.use(createMiddleware({
  clientId: 'your-app-id',
  shouldCaptureExpressRequest: (req) =>
    !req.path.startsWith('/health') && !req.path.startsWith('/static'),
}));

Filter errors

Skip expected 4xx errors:

app.use(createErrorMiddleware({
  clientId: 'your-app-id',
  shouldCaptureError: (err, req) => (err as any).status >= 500,
}));

Session access

app.get('/session', (req, res) => {
  const session = req.fa.getSession();
  res.json({ sessionId: session?.id });
});