Install Node.js SDK

If you're working with Node.js (versions 20+), the official Leanbase-node library is the simplest way to integrate your software with Leanbase. This library uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance. And in addition to event capture, feature flags are supported as well.

Installation

Run either npm or yarn in terminal to add it to your project:

In your app, set your project API key before making any calls.

You can find your project API key and instance address in the project settings page in Leanbase.

Note: As a rule of thumb, we do not recommend hardcoding API keys. Setting it as an environment variable is preferred.

Options

featureFlagsPollingInterval

Note: When using Leanbase in an AWS Lambda function or a similar serverless function environment, make sure you set flushAt to 1 and flushInterval to 0. Also, remember to always call await Leanbase.shutdown() at the end to flush and send all pending events.

Capturing events

You can send custom events using capture:

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can include additional information with the event by including a properties object:

Capturing pageviews

If you're aiming for a backend-only implementation of Leanbase and won't be capturing events from your frontend, you can send $pageview events from your backend like so:

Person profiles and properties

The Node SDK captures identified events by default. These create person profiles. To set person properties in these profiles, include them when capturing an event using $set and $set_once:

To capture anonymous events without person profiles, set the event's $process_person_profile property to false:

Alias

Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.

In this case, you can use alias to assign another distinct ID to the same user.

We strongly recommend reading our docs on alias to best understand how to correctly use this method.

Overriding GeoIP properties

By default, a user's GeoIP properties are set using the IP address they use to capture events on the frontend. You may want to override the these properties when evaluating feature flags. A common reason to do this is when you're not using Leanbase on your frontend, so the user has no GeoIP properties.

You can override GeoIP properties by including them in the person_properties parameter when evaluating feature flags. This is useful when you're evaluating flags on your backend and want to use the client's location instead of your server's location.

The following GeoIP properties can be overridden:

• $geoip_country_code

• $geoip_country_name

• $geoip_city_name

• $geoip_city_confidence

• $geoip_continent_code

• $geoip_continent_name

• $geoip_latitude

• $geoip_longitude

• $geoip_postal_code

• $geoip_subdivision_1_code

• $geoip_subdivision_1_name

• $geoip_subdivision_2_code

• $geoip_subdivision_2_name

• $geoip_subdivision_3_code

• $geoip_subdivision_3_name

• $geoip_time_zone

Simply include any of these properties in the person_properties parameter alongside your other person properties when calling feature flags.

You can also explicitly chose to enable or disable GeoIP for a single capture request like so:

Group analytics

Group analytics enable you to associate an event with a group (e.g. teams, organizations, etc.). Read the group analytics guide for more information.

To create a group or update its properties, use groupIdentify:

name is a special property which is used in the Leanbase UI for the name of the group. If you don't specify a name property, the group ID is used instead.

If the optional distinctId parameter is not provided in the group identify call, it defaults to ${groupType}_${groupKey} (e.g., $company_company_id_in_your_db in the example above). This default behavior results in each group appearing as a separate person in Leanbase. To avoid this, it's often more practical to use a consistent distinctId, such as group_identifier.

Once a group is created, you can use the capture method and pass in the groups parameter to capture an event with group analytics.

GeoIP properties

Before Leanbase-node v3.0, we added GeoIP properties to all incoming events by default. We also used these properties for feature flag evaluation, based on the IP address of the request. This isn't ideal since they are created based on your server IP address, rather than the user's, leading to incorrect location resolution.

As of Leanbase-node v3.0, the default now is to disregard the server IP, not add the GeoIP properties, and not use the values for feature flag evaluations.

You can go back to previous behavior by setting disableGeoip to false in your initialization:

The list of properties that this overrides:

1. $geoip_city_name

2. $geoip_country_name

3. $geoip_country_code

4. $geoip_continent_name

5. $geoip_continent_code

6. $geoip_postal_code

7. $geoip_time_zone

You can also explicitly chose to enable or disable GeoIP for a single capture request like so:

Shutdown

You should call shutdown on your program's exit to exit cleanly:

Debugging and exceptions

If you are experiencing issues with the SDK it could be a number of things from an incorrectly configured API key, to some other network related issues.

The SDK does not throw errors for things happening in the background to ensure it doesn't affect your process. You can however hook into the errors to get more information:

Or you can enable debugging to get verbose logs about all the inner workings of the SDK.

Short-lived processes like serverless environments

The Node SDK is designed to queue and batch requests in the background to optimize API calls and network time. As serverless environments like AWS Lambda or Vercel Functions are short-lived, we provide a few options to ensure all events are captured.

First, we recommend using the captureImmediate method instead of capture to ensure the event is captured before the function shuts down. It guarantees the HTTP request finishes before your function continues (or shuts down).

Second, we recommend setting flushAt to 1 and flushInterval to 0 to ensure the events are sent immediately. These set the queue to flush immediately, both in terms of events and time.

Third, we provide a method shutdown() which can be awaited to ensure all queued events are sent to the API. For example:

This is also useful for shutting down a standard Node.js app.

LLM analytics

You can capture LLM usage and performance data by combining the Leanbase-node and @Leanbase/ai libraries. These work with LLM providers like OpenAI and Vercel's AI SDKs. Learn more in our LLM analytics docs.

Error tracking

You can capture errors using the Leanbase-node library. This enables you to see stack traces, source code, and watch associated session recordings to improve your application stability. Learn more in our error tracking docs.