Express

Installation

npm install @helionlabs/express

Usage

The default export of @helionlabs/express is a factory function that returns an Express middleware. The middleware attaches a Helion SDK instance to req.helion on every incoming request, scoped with the correct client IP and User-Agent headers extracted automatically.

import express from 'express';
import createHelionMiddleware from '@helionlabs/express';

const app = express();

app.use(
  createHelionMiddleware({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    // trackRequest(url) {
    //   return url.includes('/v1');
    // },
    // getProfileId(req) {
    //   return req.user.id;
    // },
  })
);

app.get('/sign-up', (req, res) => {
  req.helion.track('sign-up', {
    email: req.body.email,
  });
  res.send('OK');
});

app.listen(3000);

Options

Common options

• apiUrl - The url of the helion API or your self-hosted instance
• clientId - The client id of your application
• clientSecret - The client secret of your application (only required for server-side events)
• filter - A function that will be called before sending an event. If it returns false, the event will not be sent
• disabled - If true, the library will not send any events

Express-specific options

• trackRequest(url: string): boolean — Called on every request. Return true to automatically track a request event for that URL.
• getProfileId(req: Request): string — Extracts a profile ID from the request (e.g., from req.user.id) to attach to auto-tracked request events.

Working with Groups

Groups enable account-level analytics from your route handlers. See the Groups guide for the full walkthrough.

app.post('/login', async (req, res) => {
  const user = await loginUser(req.body);

  // Identify the user
  req.helion.identify({ profileId: user.id, email: user.email });

  // Sync the group entity with current properties
  req.helion.upsertGroup({
    id: user.organizationId,
    type: 'company',
    name: user.organizationName,
    properties: { plan: user.plan },
  });

  // Link the user to their group
  req.helion.setGroup(user.organizationId);

  res.json({ ok: true });
});

TypeScript

The @helionlabs/express package augments the Express Request interface automatically. If TypeScript does not pick up req.helion, add the following to a .d.ts file in your project:

import { Helion } from '@helionlabs/express';

declare global {
  namespace Express {
    export interface Request {
      helion: Helion;
    }
  }
}