Node.js

If you're working with Node.js, the official posthog-node library is the simplest way to integrate your software with PostHog. 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:

npm install posthog-node --save
# or
yarn add posthog-node

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

import { PostHog } from 'posthog-node'

const client = new PostHog(
    '<ph_project_api_key>',
    { host: 'https://us.i.posthog.com' }
)

await client.shutdown() 

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

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

Options

Note: When using PostHog 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 posthog.shutdown() at the end to flush and send all pending events.

Capturing events

You can send custom events using capture:

client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'user signed up',
})

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 also include additional information in the event by setting the properties value:

client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'user signed up',
    properties: {
        login_type: 'email',
        is_free_trial: true,
    },
})

Capturing pageviews

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

client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: '$pageview',
    properties: {
        $current_url: 'https://example.com',
    },
})

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:

client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'movie_played',
    properties: {
        $set: { name: 'Max Hedgehog'  },
        $set_once: { initial_url: '/blog' },
    },
})

For more details on the difference between $set and $set_once, see our person properties docs.

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

client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'movie_played',
    properties: {
        $process_person_profile: 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.

client.alias({
    distinctId: 'distinct_id',
    alias: 'alias_id',
})

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

Feature flags

PostHog's feature flags enable you to safely deploy and roll back new features.

There are 2 steps to implement feature flags in Node:

Step 1: Evaluate the feature flag value

Boolean feature flags

const isFeatureFlagEnabled = await client.isFeatureEnabled('flag-key', 'distinct_id_of_your_user')
if (isFeatureFlagEnabled) {
    // Your code if the flag is enabled

    // Optional: fetch the payload
    const matchedFlagPayload = await client.getFeatureFlagPayload('flag-key', 'distinct_id_of_your_user')
}

Multivariate feature flags

const enabledVariant = await client.getFeatureFlag('flag-key', 'distinct_id_of_your_user')

if (enabledVariant === 'variant-key') {  // replace 'variant-key' with the key of your variant
    // Do something differently for this user

    // Optional: fetch the payload
    const matchedFlagPayload = await client.getFeatureFlagPayload('flag-key', 'distinct_id_of_your_user')
}

Step 2: Include feature flag information when capturing events

If you want use your feature flag to breakdown or filter events in your insights, you'll need to include feature flag information in those events. This ensures that the feature flag value is attributed correctly to the event.

Note: This step is only required for events captured using our server-side SDKs or API.

There are two methods you can use to include feature flag information in your events:

Method 1: Include the $feature/feature_flag_name property

In the event properties, include $feature/feature_flag_name: variant_key:

client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    properties: {
        '$feature/feature-flag-key': 'variant-key' // replace feature-flag-key with your flag key. Replace 'variant-key' with the key of your variant
    },
})

Method 2: Set sendFeatureFlags to true

The capture() method has an optional argument sendFeatureFlags, which is set to false by default. By setting this to true, feature flag information will automatically be sent with the event.

Note that by doing this, PostHog will make an additional request to fetch feature flag information before capturing the event. So this method is only recommended if you don't mind the extra API call and delay.

client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    sendFeatureFlags: true,
})

Fetching all flags for a user

You can fetch all flag values for a single user by calling getAllFlags() or getAllFlagsAndPayloads().

This is useful when you need to fetch multiple flag values and don't want to make multiple requests.

await client.getAllFlags('distinct_id_of_your_user') 
await client.getAllFlagsAndPayloads('distinct_id_of_your_user')

Sending $feature_flag_called events

Capturing $feature_flag_called events enable PostHog to know when a flag was accessed by a user and thus provide analytics and insights on the flag. By default, we send a these event when:

1. You call posthog.getFeatureFlag() or posthog.isFeatureEnabled(), AND
2. It's a new user, or the value of the flag has changed.

Note: Tracking whether it's a new user or if a flag value has changed happens in a local cache. This means that if you reinitialize the PostHog client, the cache resets as well – causing $feature_flag_called events to be sent again when calling getFeatureFlag or isFeatureEnabled. PostHog is built to handle this, and so duplicate $feature_flag_called events won't affect your analytics.

You can disable automatically capturing $feature_flag_called events. For example, when you don't need the analytics, or it's being called at such a high volume that sending events slows things down.

To disable it, set the sendFeatureFlagEvents argument in your function call, like so:

const isFeatureFlagEnabled = await client.isFeatureEnabled(
    'flag-key', 
    'distinct_id_of_your_user',
    {
        'sendFeatureFlagEvents': false
    })

Advanced: Overriding server properties

Sometimes, you may want to evaluate feature flags using person properties, groups, or group properties that haven't been ingested yet, or were set incorrectly earlier.

You can provide properties to evaluate the flag with by using the person properties, groups, and group properties arguments. PostHog will then use these values to evaluate the flag, instead of any properties currently stored on your PostHog server.

For example:

await client.getFeatureFlag(
    'flag-key',
    'distinct_id_of_the_user',
    {
        personProperties: {
            'property_name': 'value'
        },
        groups: {
            "your_group_type": "your_group_id",
            "another_group_type": "your_group_id",
        },
        groupProperties: {
            'your_group_type': {
                'group_property_name': 'value'
            },
            'another_group_type': {
                'group_property_name': 'value'
            } 
        },
    }
)

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 PostHog on your frontend, so the user has no GeoIP properties.

Currently PostHog does not provide a way to override GeoIP properties using our SDKs. Our API, however, does allow you do this. See our API docs on how to override GeoIP properties for more details.

Request timeout

You can configure the feature_flag_request_timeout_ms parameter when initializing your PostHog client to set a flag request timeout. This helps prevent your code from being blocked in the case when PostHog's servers are too slow to respond. By default, this is set at 3 seconds.

const client = new PostHog('<ph_project_api_key>', { 
        api_host: 'https://us.i.posthog.com',
        feature_flag_request_timeout_ms: 3000 // Time in milliseconds. Default is 3000 (3 seconds).
    }
)

Error handling

When using the PostHog SDK, it's important to handle potential errors that may occur during feature flag operations. Here's an example of how to wrap PostHog SDK methods in an error handler:

async function handleFeatureFlag(client, flagKey, distinctId) {
    try {
        const isEnabled = await client.isFeatureEnabled(flagKey, distinctId);
        console.log(`Feature flag '${flagKey}' for user '${distinctId}' is ${isEnabled ? 'enabled' : 'disabled'}`);
        return isEnabled;
    } catch (error) {
        console.error(`Error fetching feature flag '${flagKey}': ${error.message}`);
        // Optionally, you can return a default value or throw the error
        // return false; // Default to disabled
        throw error;
    }
}

// Usage example
try {
    const flagEnabled = await handleFeatureFlag(client, 'new-feature', 'user-123');
    if (flagEnabled) {
        // Implement new feature logic
    } else {
        // Implement old feature logic
    }
} catch (error) {
    // Handle the error at a higher level
    console.error('Feature flag check failed, using default behavior');
    // Implement fallback logic
}

Local Evaluation

Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.

It is best practice to use local evaluation flags when possible, since this enables you to resolve flags faster and with fewer API calls.

For details on how to implement local evaluation, see our local evaluation guide.

const flagValue = await client.getFeatureFlag('flag-key', 'user distinct id', {groups:{'organisation': 'google'}, groupProperties:{'organisation': {'is_authorized': True}})

Reloading feature flags

When initializing PostHog, you can configure the interval at which feature flags are polled (fetched from the server). However, if you need to force a reload, you can use reloadFeatureFlags:

await client.reloadFeatureFlags()

// Do something with feature flags here

Experiments (A/B tests)

Since experiments use feature flags, the code for running an experiment is very similar to the feature flags code:

const variant = await client.getFeatureFlag('experiment-feature-flag-key', 'user_distinct_id')

if (variant === 'variant-name') {
    // do something
}

It's also possible to run experiments without using feature flags.

Group analytics

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

Note: This is a paid feature and is not available on the open-source or free cloud plan. Learn more here.

• Capture an event and associate it with a group

client.capture({
    event: 'some_event',
    distinctId: 'user_distinct_id',
    groups: { company: 'company_id_in_your_db' },
})

• Update properties on a group

client.groupIdentify({
    groupType: 'company',
    groupKey: 'company_id_in_your_db',
    properties: {
        name: 'Awesome Inc',
        employees: 11,
    },
    // optional distinct ID to associate event with an existing person
    distinctId: 'xyz'
})

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

If the optional distinct_id 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 will result in each group appearing as a separate person in PostHog. To avoid this, it's often more practical to use a consistent distinct_id, such as group_identifier.

GeoIP properties

Before posthog-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 posthog-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:

const posthog = new PostHog(PH_API_KEY, {
  host: PH_HOST,
  disableGeoip: false
})

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:

client.capture({
  distinctId: distinctId,
  event: 'your_event',
  disableGeoip: `true`,
})

Shutdown

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

// Stop pending pollers and flush any remaining events
await client.shutdown()

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:

client.on("error", (err) => {
  // Whatever handling you want
  console.error("PostHog had an error!", err)
})

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

client.debug()

Using in a short-lived process like AWS Lambda

PostHogs's client SDKs are all designed to queue and batch requests in the background to optimise API calls and network time. For lambda environments (or also when shutting down a standard Node.js app) we provide a method shutdown() which can be awaited and ensures the queued events are all flushed to the API.

For example:

export const handler() {
  client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'thing_happened'
  })

  client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'other_thing_happened'
  })

  // So far 2 events are queued but not sent

  // Calling shutdown, flushed the queue but batched into 1 API call for maximum efficiency
  await client.shutdown()
}

Sentry integration

When using Sentry in Node.js, you can connect to PostHog in order to link Sentry errors to PostHog user profiles.

Example implementation

See the posthog-node project for a complete example.

import { PostHog, PostHogSentryIntegration } from 'posthog-node'
import * as Sentry from '@sentry/node'

const posthog = new PostHog(PH_API_KEY, { host: PH_HOST })

Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
  integrations: [new PostHogSentryIntegration(posthog)],
})

// Set the PostHog distinctId for the relevant session either globally for all events
Sentry.setTag(PostHogSentryIntegration.POSTHOG_ID_TAG, 'my-nodejs-service');

// or contextually for example within an api request
try {
    myFunction()
} catch(err) {
  Sentry.captureException(err, {
    tags: {
      [PostHogSentryIntegration.POSTHOG_ID_TAG]: request.user.id,
    },
  })
}

Upgrading from V1 to V2

V2.x.x of the Node.js library is completely rewritten in Typescript and is based on a new JS core shared with other JavaScript based libraries with the goal of ensuring new features and fixes reach the different libraries at the same pace.

With the release of V2, the API was kept mostly the same but with some small changes and deprecations:

1. The minimum PostHog version requirement is 1.38
2. The callback parameter passed as an optional last argument to most of the methods is no longer supported
3. The method signature for isFeatureEnabled and getFeatureFlag is slightly modified. See the above documentation for each method for more details.
4. For specific changes, see the CHANGELOG