Express SDK | Documentation

The Express package creates requestMiddleware and errorMiddlewarethat automatically send request and server_error events. It also attaches the SDK instance to req.fa for manual tracking in routes.

Installation

Install the package

Terminal

npm install @flash-analytics/express@2.1.8

Terminal

pnpm add @flash-analytics/express@2.1.8

Set environment variables

.envTerminal

FLASH_CLIENT_ID=00000000-0000-4000-8000-000000000000
FLASH_CLIENT_SECRET=your-secret-key

Add middleware to your app

Register requestMiddleware before your routes and errorMiddlewareafter all routes (standard Express error-handler position).

server.tsTypeScript

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

const app = express();

const { sdk, requestMiddleware, errorMiddleware } = createFlashAnalytics({
  clientId: process.env.FLASH_CLIENT_ID!,
  clientSecret: process.env.FLASH_CLIENT_SECRET,
  resolveUserId: (req) => (req as any).user?.id,
  shouldCaptureExpressRequest: (req) => !req.path.startsWith('/health'),
  shouldCaptureError: (err) => err.name !== 'ValidationError',
});

// Must be before routes
app.use(requestMiddleware);

// Your routes here
app.get('/', (req, res) => res.json({ ok: true }));

// Must be after all routes
app.use(errorMiddleware);

app.listen(3000);

Middleware order matters

requestMiddleware must come before your routes. errorMiddleware must come after all routes — this is standard Express error handler convention.

Track custom events per route

Use req.fa to send route-specific events from any handler.

TypeScript

app.post('/checkout', async (req, res) => {
  req.fa.track('checkout_created', {
    profileId: req.user?.id,
    orderId: req.body.orderId,
    cartValue: req.body.total,
  });

  // Process checkout...
  res.json({ ok: true });
});

Auto-captured events

request

Sent for every HTTP request that passes the shouldCaptureExpressRequest filter. Includes method, path, status code, and resolved user ID.

server_error

Sent for errors that reach the error middleware and pass the shouldCaptureError filter. Includes error name and stack.

Configuration options

clientIdRequired

Your Flash app UUID (same as appId in other SDKs).

clientSecret

Optional secret sent as flash-analytics-client-secret. Keep server-only.

resolveUserId(req)

Map an Express request to a Flash profileId.

shouldCaptureExpressRequest(req)

Return false to skip automatic request events (e.g. health checks).

shouldCaptureError(err, req)

Return false to skip automatic server_error events (e.g. validation errors).

debug

Logs background tracking status. Use in development only.

onTrackSuccess(eventName, response)

Callback after middleware event succeeds.

onTrackError(eventName, error)

Callback after middleware event fails.

Using the SDK directly

The returned sdk instance is a full FlashAnalytics instance. Use it outside of request contexts (e.g. startup events, scheduled jobs).

TypeScript

const { sdk } = createFlashAnalytics({ clientId: process.env.FLASH_CLIENT_ID! });

// At server startup
sdk.track('server_started', { version: process.env.npm_package_version });

// In a cron job
sdk.track('daily_report_generated', { reportDate: today });

Session access

TypeScript

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