@entrolytics/fastify-middleware

Fastify plugin for Entrolytics - First-party growth analytics for the edge.

Features

• 🚀 Fastify Plugin Architecture - Native Fastify plugin
• 📊 Automatic Page View Tracking - Track all requests automatically
• 🔍 Error Tracking - Automatic error response tracking
• 🎯 Custom Event Tracking - Track custom events via request.entrolytics
• 🛡️ Type-Safe - Full TypeScript support
• 🐛 Debug Mode - Built-in debugging with Fastify logger
• ⚡ Hook-Based - Uses Fastify lifecycle hooks

Installation

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

Quick Start

import Fastify from 'fastify'
import entrolyticsPlugin from '@entrolytics/fastify-middleware'

const fastify = Fastify({ logger: true })

await fastify.register(entrolyticsPlugin, {
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  debug: true // optional
})

fastify.get('/', async (request, reply) => {
  return { hello: 'world' }
})

await fastify.listen({ port: 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:

await fastify.register(entrolyticsPlugin, {
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  trackPageViews: true // enabled by default
})

Custom Event Tracking

Track custom events using request.entrolytics:

fastify.post('/api/purchase', async (request, reply) => {
  // Process purchase...
  
  await request.entrolytics.track('purchase', {
    amount: request.body.amount,
    product_id: request.body.productId
  })
  
  return { success: true }
})

User Identification

Identify users for tracking:

fastify.post('/api/login', async (request, reply) => {
  // Authenticate user...
  
  await request.entrolytics.identify(user.id, {
    email: user.email,
    name: user.name,
    plan: user.plan
  })
  
  return { success: true }
})

Manual Page Tracking

Track specific pages manually:

fastify.get('/dashboard', async (request, reply) => {
  await request.entrolytics.page('Dashboard', {
    user_type: request.user?.type
  })
  
  return { page: 'dashboard' }
})

Error Tracking

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

await fastify.register(entrolyticsPlugin, {
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  trackErrors: true // enabled by default
})

fastify.get('/not-found', async (request, reply) => {
  reply.code(404)
  return { error: 'Not Found' } // Automatically tracked
})

Advanced Usage

With TypeScript

import Fastify from 'fastify'
import entrolyticsPlugin from '@entrolytics/fastify-middleware'

const fastify = Fastify({ logger: true })

await fastify.register(entrolyticsPlugin, {
  endpoint: process.env.ENTROLYTICS_ENDPOINT!,
  apiKey: process.env.ENTROLYTICS_API_KEY!,
  websiteId: process.env.ENTROLYTICS_WEBSITE_ID!,
  debug: process.env.NODE_ENV === 'development'
})

fastify.post<{
  Body: { event: string; properties: Record<string, any> }
}>('/api/events', async (request, reply) => {
  await request.entrolytics.track(request.body.event, request.body.properties)
  return { tracked: true }
})

Conditional Tracking

fastify.addHook('onRequest', async (request, reply) => {
  if (request.url.startsWith('/api/internal')) {
    // Skip tracking for internal API routes
    request.entrolytics = {
      track: async () => {},
      identify: async () => {},
      page: async () => {}
    }
  }
})

With Error Handler

await fastify.register(entrolyticsPlugin, {
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id'
})

fastify.setErrorHandler(async (error, request, reply) => {
  await request.entrolytics.track('error', {
    error_message: error.message,
    error_stack: error.stack,
    path: request.url
  })
  
  reply.code(500).send({ error: 'Internal Server Error' })
})

With Authentication

import fastifyJwt from '@fastify/jwt'

await fastify.register(fastifyJwt, { secret: 'supersecret' })

await fastify.register(entrolyticsPlugin, {
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id'
})

fastify.addHook('onRequest', async (request, reply) => {
  try {
    await request.jwtVerify()
    await request.entrolytics.identify(request.user.id, {
      email: request.user.email
    })
  } catch (err) {
    // Not authenticated
  }
})

API Reference

request.entrolytics.track(event, properties?)

Track a custom event.

Parameters:

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

Returns: Promise<void>

request.entrolytics.identify(userId, traits?)

Identify a user.

Parameters:

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

Returns: Promise<void>

request.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
6. Use Fastify Hooks - Leverage Fastify's lifecycle hooks for advanced tracking

Compatibility

• Fastify 4.x and 5.x
• Node.js 24.x or higher

License

MIT