@entrolytics/express-middleware

Express middleware for Entrolytics - First-party growth analytics for the edge.

Features

• 🚀 Easy Integration - Simple middleware setup
• 📊 Automatic Page View Tracking - Track all requests automatically
• 🔍 Error Tracking - Automatic error response tracking
• 🎯 Custom Event Tracking - Track custom events via res.locals
• 🛡️ Type-Safe - Full TypeScript support
• 🐛 Debug Mode - Built-in debugging capabilities

Installation

npm install @entrolytics/express-middleware
# or
yarn add @entrolytics/express-middleware
# or
pnpm add @entrolytics/express-middleware

Quick Start

import express from 'express'
import { entrolyticsMiddleware } from '@entrolytics/express-middleware'

const app = express()

app.use(entrolyticsMiddleware({
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  debug: true // optional
}))

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

app.listen(3000)

Configuration

EntrolyticsConfig

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | endpoint | string | Yes | - | Your Entrolytics endpoint | | apiKey | string | Yes | - | Your API key | | websiteId | string | Yes | - | Your website ID | | debug | boolean | No | false | Enable debug logging | | trackPageViews | boolean | No | true | Automatically track page views | | trackErrors | boolean | No | true | Automatically track errors |

Usage

Automatic Page View Tracking

Page views are tracked automatically for all requests:

app.use(entrolyticsMiddleware({
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  trackPageViews: true // enabled by default
}))

Custom Event Tracking

Track custom events using res.locals.entrolytics:

app.post('/api/purchase', async (req, res) => {
  // Process purchase...
  
  await res.locals.entrolytics?.track('purchase', {
    amount: req.body.amount,
    product_id: req.body.productId
  })
  
  res.json({ success: true })
})

User Identification

Identify users for tracking:

app.post('/api/login', async (req, res) => {
  // Authenticate user...
  
  await res.locals.entrolytics?.identify(user.id, {
    email: user.email,
    name: user.name,
    plan: user.plan
  })
  
  res.json({ success: true })
})

Manual Page Tracking

Track specific pages manually:

app.get('/dashboard', async (req, res) => {
  await res.locals.entrolytics?.page('Dashboard', {
    user_type: req.user?.type
  })
  
  res.render('dashboard')
})

Error Tracking

Errors (4xx and 5xx responses) are tracked automatically:

app.use(entrolyticsMiddleware({
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  trackErrors: true // enabled by default
}))

app.get('/not-found', (req, res) => {
  res.status(404).send('Not Found') // Automatically tracked
})

Advanced Usage

With TypeScript

import express, { Request, Response } from 'express'
import { entrolyticsMiddleware } from '@entrolytics/express-middleware'

const app = express()

app.use(entrolyticsMiddleware({
  endpoint: process.env.ENTROLYTICS_ENDPOINT!,
  apiKey: process.env.ENTROLYTICS_API_KEY!,
  websiteId: process.env.ENTROLYTICS_WEBSITE_ID!,
  debug: process.env.NODE_ENV === 'development'
}))

app.post('/api/events', async (req: Request, res: Response) => {
  await res.locals.entrolytics?.track('custom_event', {
    ...req.body
  })
  
  res.json({ tracked: true })
})

Conditional Tracking

app.use((req, res, next) => {
  if (req.path.startsWith('/api/')) {
    return next() // Skip tracking for API routes
  }
  
  entrolyticsMiddleware({
    endpoint: 'https://entrolytics.click',
    apiKey: 'your-api-key',
    websiteId: 'your-website-id'
  })(req, res, next)
})

With Error Handler

app.use(entrolyticsMiddleware({
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id'
}))

// Your routes...

app.use((err, req, res, next) => {
  res.locals.entrolytics?.track('error', {
    error_message: err.message,
    error_stack: err.stack,
    path: req.path
  })
  
  res.status(500).send('Internal Server Error')
})

API Reference

res.locals.entrolytics.track(event, properties?)

Track a custom event.

Parameters:

• event (string): Event name
• properties (object, optional): Event properties

Returns: Promise<void>

res.locals.entrolytics.identify(userId, traits?)

Identify a user.

Parameters:

• userId (string): User ID
• traits (object, optional): User traits

Returns: Promise<void>

res.locals.entrolytics.page(name?, properties?)

Track a page view.

Parameters:

• name (string, optional): Page name
• properties (object, optional): Page properties

Returns: Promise<void>

Best Practices

1. Use Environment Variables - Store credentials in environment variables
2. Enable Debug Mode in Development - Set debug: true during development
3. Track Meaningful Events - Focus on business-critical events
4. Add Context - Include relevant properties with events
5. Handle Errors Gracefully - Tracking failures won't crash your app

License

MIT