How to add analytics to Express

Server-side analytics gives you reliable event tracking that cannot be blocked by ad blockers or browser extensions. The Helion Express middleware wraps the JavaScript SDK and attaches it to every request, making it simple to track events throughout your application.

Helion is an open-source alternative to Mixpanel and Amplitude. You get powerful analytics with full control over your data, and you can self-host if privacy requirements demand it.

Prerequisites

• An Express application
• An Helion account (sign up free)
• Your Client ID and Client Secret from the Helion dashboard

Server-side tracking requires a clientSecret for authentication since the server cannot rely on browser CORS headers to verify the request origin.

Install the SDK

The Express SDK is a lightweight middleware that creates an Helion instance for each request. Install it with npm (pnpm and yarn work too).

npm install @helionlabs/express

Add the middleware

The middleware attaches the Helion SDK to every request as req.op. Add it early in your middleware chain so it is available in all your route handlers.

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

const app = express();

app.use(express.json());

app.use(
  createHelionMiddleware({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
  })
);

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

You should store your credentials in environment variables rather than hardcoding them. This keeps secrets out of version control and makes it easy to use different credentials in development and production.

app.use(
  createHelionMiddleware({
    clientId: process.env.HELION_CLIENT_ID!,
    clientSecret: process.env.HELION_CLIENT_SECRET!,
  })
);

The middleware also forwards the client IP address and user-agent from incoming requests, so geographic and device data will be accurate even though events originate from your server.

Track events

Once the middleware is in place, you can track events in any route handler by calling req.op.track(). The first argument is the event name and the second is an object of properties you want to attach.

app.post('/signup', async (req, res) => {
  const { email, name } = req.body;

  req.op.track('user_signed_up', {
    email,
    name,
    source: 'website',
  });

  const user = await createUser({ email, name });
  res.json({ success: true, user });
});

You can track any event that matters to your business. Common examples include form submissions, purchases, feature usage, and API errors.

app.post('/contact', async (req, res) => {
  const { email, message } = req.body;

  req.op.track('contact_form_submitted', {
    email,
    message_length: message.length,
  });

  await sendContactEmail(email, message);
  res.json({ success: true });
});

Automatic request tracking

The middleware can automatically track every request if you provide a trackRequest function. This is useful for monitoring API usage without manually adding tracking calls to each route.

app.use(
  createHelionMiddleware({
    clientId: process.env.HELION_CLIENT_ID!,
    clientSecret: process.env.HELION_CLIENT_SECRET!,
    trackRequest: (url) => url.startsWith('/api/'),
  })
);

When trackRequest returns true, the middleware sends a request event with the URL, method, and query parameters.

Identify users

To associate events with specific users, use the getProfileId option in the middleware configuration. This function receives the request object and should return the user's ID.

app.use(
  createHelionMiddleware({
    clientId: process.env.HELION_CLIENT_ID!,
    clientSecret: process.env.HELION_CLIENT_SECRET!,
    getProfileId: (req) => req.user?.id,
  })
);

You can also send user profile data with req.op.identify(). This updates the user's profile in Helion with properties like name, email, and any custom attributes.

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

  req.op.identify({
    profileId: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    properties: {
      plan: user.plan,
      signupDate: user.createdAt,
    },
  });

  req.op.track('user_logged_in', { method: 'email' });
  res.json({ success: true, user });
});

Increment profile properties

If you want to track cumulative values on a user profile, like login count or total purchases, use the increment method.

req.op.increment({
  profileId: user.id,
  property: 'login_count',
  value: 1,
});

Verify your setup

Start your Express server and trigger a few events by making requests to your endpoints. Open the Helion dashboard and navigate to the Real-time view to see events as they arrive.

If events are not appearing, check your server logs for error responses from Helion. Verify that both clientId and clientSecret are correct and that the middleware is added before your routes.

TypeScript support

The Express SDK automatically extends the Request interface to include req.op. If your TypeScript configuration does not pick this up, you can extend the interface manually in a declaration file.

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

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

Next steps

The Express SDK reference covers all available options and methods. If you are using a different Node.js framework, the Node.js tracking guide shows how to use the base SDK directly. For comparing Helion to other analytics tools, see the Mixpanel alternative page.