Skip to main content

Server SDK Integration Guide

This guide explains how to integrate the Pulse Server SDK and its Express and NestJS wrappers into your backend applications. It covers installation, configuration, and usage for each supported framework.

Overview​

The Pulse Server SDK enables backend services to access Pulse settings, tracking, and context propagation. It is framework-agnostic and can be used directly or via wrappers for Express and NestJS.

  • @pulse/server: Core SDK for Node.js backends.
  • @pulse/express: Express.js middleware for request context.
  • @pulse/nest: NestJS module and middleware for seamless integration.

Installation​

Install the required packages from your registry:

npm install @pulse/server @pulse/express @pulse/nest

Configuration​

All integrations use a common configuration object. The most important option is app, which identifies your application. You can also specify settings for the tracker, settings, and other features.

Example configuration:

const config = {
  app: "your-app-name",
  settings: {
    defaults: {
      /* key-value pairs */
    },
    remoteSettingEnabled: true,
  },
  tracker: {
    version: "your app version",
  },
};

Usage​

1. Direct Server SDK Usage​

Use this approach for custom Node.js servers or advanced use cases.

import { createClient } from "@pulse/server";
import { pulse } from "@pulse/core";

const client = createClient(config);

// Create a Pulse context for a request
const pulse = client.createAsyncContext({
  user_id: "user-123",
  // ...other context fields
});

// Access settings
const value = await pulse.get("setting_name", "tag_name");

2. Express Integration​

Use the Express middleware to automatically inject Pulse context into each request.

import { pulse } from "@pulse/core";
import { usePulse } from "@pulse/express";
import express from "express";

const host = process.env["HOST"] ?? "localhost";
const port = process.env["PORT"] ? Number(process.env["PORT"]) : 9000;

const app = express();

// Initialize Pulse middleware with configuration
app.use(
  usePulse({
    app: "your-app-name",
  })
);

app.get("/", async (_req, res) => {
  let settingValue = null;

  try {
    settingValue = await pulse.get("setting_name", "tag_name");
  } catch (error) {
    settingValue = { error: "Failed to fetch setting" };
  }

  res.send({
    message: "Hello API!",
    setting: settingValue,
  });
});

Key Points:

  • The middleware is initialized with your app name.
  • In route handlers, you can access the Pulse context and fetch settings asynchronously.
  • Error handling is included for robustness.

3. NestJS Integration​

Use the NestJS module and middleware for seamless integration.

import { Module } from "@nestjs/common";
import { PulseModule } from "@pulse/nest";

@Module({
  imports: [PulseModule.forRoot(config)],
})
export class AppModule {}
  • The PulseMiddleware is automatically applied to all routes.
  • Inject the Pulse client or access context in your services/controllers as needed.

API Reference​

createClient(config)​

Creates a Pulse client instance with the given configuration.

Express: usePulse(config)​

Returns Express middleware that injects Pulse context into each request.

NestJS: PulseModule.forRoot(config)​

Registers the Pulse module and middleware for your NestJS app.

Notes​

  • Always initialize the SDK with your application name and relevant configuration.
  • For advanced scenarios, refer to the SDK source or contact the Pulse team.