Skip to main content

​
Installation

npm install @userboost/sdk

​
Basic Setup

import { UserBoost } from "@userboost/sdk";

// Initialize with your server-side API key
UserBoost.init({
  apiKey: process.env.USERBOOST_API_KEY,
  debug: process.env.NODE_ENV === "development",
});
This example uses ES modules. For CommonJS, use const UserBoost = require("@userboost/sdk") instead.

​
Tracking Events

​
Basic Event Tracking

// Track user action
UserBoost.event("user_signed_up", {
  user: {
    id: "user_123",
    email: "john@example.com",
    traits: {
      plan: "free",
    },
  },
});

// Track feature usage
UserBoost.event("feature_used", {
  user: {
    id: "user_123",
  },
  properties: {
    feature: "dashboard",
    action: "viewed",
  },
});

​
User Identification

// Update user profile
UserBoost.identify({
  id: "user_123",
  email: "john@example.com",
  traits: {
    name: "John Doe",
    plan: "premium",
    created_at: "2025-01-01T00:00:00Z",
  },
});

​
TypeScript Support

The SDK includes full TypeScript definitions: 
import { UserBoost } from "@userboost/sdk";

interface UserTraits {
  email: string;
  name: string;
  plan: "free" | "premium" | "enterprise";
}

interface EventData {
  user: {
    id: string;
    email?: string;
    traits?: Record<string, any>;
  };
  properties?: Record<string, any>;
}

// Type-safe event tracking
UserBoost.event("user_registered", {
  user: {
    id: "user_123",
    email: "john@example.com",
    traits: {
      plan: "free",
    },
  },
} as EventData);

// Type-safe user identification
UserBoost.identify({
  id: "user_123",
  email: "john@example.com",
  traits: {
    name: "John Doe",
    plan: "premium",
  },
});

​
Environment Configuration

// .env file
USERBOOST_API_KEY = ub_live_your_api_key_here;
NODE_ENV = production;

// Development setup
UserBoost.init({
  apiKey: process.env.USERBOOST_API_KEY,
  debug: process.env.NODE_ENV === "development",
  // Optional: use test endpoint for development
  endpoint:
    process.env.NODE_ENV === "development"
      ? "https://api-test.userboo.st"
      : "https://api.userboo.st",
});

​
Error Handling

// Graceful error handling
try {
  UserBoost.event("user_action", {
    user: {
      id: "user_123",
    },
    properties: {
      action: "button_click",
    },
  });
} catch (error) {
  console.error("UserBoost tracking failed:", error);
  // Continue with application flow
}

// Async error handling
UserBoost.event("user_action", { user: { id: "user_123" } }).catch((error) => {
  console.error("Event tracking failed:", error);
});

​
Best Practices

  1. Initialize once at application startup
  2. Use environment variables for API keys
  3. Handle errors gracefully - don’t break app flow
  4. Use meaningful event names that describe user actions
  5. Include user context in event properties
  6. Test in development with debug mode enabled

​
Framework Integration

The SDK works with any Node.js framework. Here are simple examples:

​
Express.js

import express from "express";
import { UserBoost } from "@userboost/sdk";

const app = express();
UserBoost.init({ apiKey: process.env.USERBOOST_API_KEY });

app.post("/api/register", (req, res) => {
  const { email, password } = req.body;

  // Your registration logic here
  const userId = createUser(email, password);

  // Track registration
  UserBoost.event("user_registered", {
    user: {
      id: userId,
      email: email,
    },
  });

  res.json({ success: true, userId });
});

​
Fastify

import fastify from "fastify";
import { UserBoost } from "@userboost/sdk";

const server = fastify();
UserBoost.init({ apiKey: process.env.USERBOOST_API_KEY });

server.post("/api/register", async (request, reply) => {
  const { email, password } = request.body;

  const userId = await createUser(email, password);

  UserBoost.event("user_registered", {
    id: userId,
    email: email,
  });

  return { success: true, userId };
});

​
Support

For Node.js SDK specific questions, contact support@userboo.st
⌘I