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)

  // Batch delivery for request, server_error, and manual track() calls
  deliveryStrategy?: {
    strategy: 'batching';
    config?: {
      size?: number;              // Default: 10, API max: 100
      timeout?: number;           // Default: 5000 ms
      fallbackToIndividual?: boolean; // Default: true
    };
  };

  // 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 });
});

Batching

Enable batching to queue auto-tracked request / server_error events and manual track() calls, then send them together through /track/batch.

For batching, prefer createFlashAnalytics so request tracking, error tracking, and shutdown flushing share the same SDK instance:

import express from 'express';
import { createFlashAnalytics } from '@flash-analytics/express';

const app = express();

const { sdk, requestMiddleware, errorMiddleware } = createFlashAnalytics({
  clientId: 'your-app-id',
  clientSecret: 'your-secret-key',
  endpoint: 'https://api.flashanalytics.app',
  deliveryStrategy: {
    strategy: 'batching',
    config: {
      size: 10,
      timeout: 5000,
      fallbackToIndividual: true,
    },
  },
});

app.use(requestMiddleware);

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

app.use(errorMiddleware);

process.once('SIGTERM', () => {
  void sdk.flushBatch();
});

Batch size is clamped to the API limit of 100 events. If /track/batch fails, the SDK retries events individually by default unless fallbackToIndividual is set to false.

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 });
});