> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userboo.st/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Official UserBoost SDK for Node.js applications with TypeScript support

## Installation

```bash theme={null}
npm install @userboost/sdk
```

## Basic Setup

```javascript theme={null}
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",
});
```

<Note>
  This example uses ES modules. For CommonJS, use `const UserBoost =
      require("@userboost/sdk")` instead.
</Note>

## Tracking Events

### Basic Event Tracking

```javascript theme={null}
// 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

```javascript theme={null}
// 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:

```typescript theme={null}
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

```javascript theme={null}
// .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

```javascript theme={null}
// 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

```javascript theme={null}
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

```javascript theme={null}
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](mailto:support@userboo.st)