references/node.md · 24000
oid 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.
Node.js
PostHog AI
client.capture({
event: 'some_event',
distinctId: 'user_distinct_id',
groups: { company: 'company_id_in_your_db' },
})
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:
Node.js
PostHog AI
const posthog = new PostHog('<ph_project_token>', {
host: 'https://us.i.posthog.com',
disableGeoip: false
})
The list of properties that this overrides:
$geoip_city_name$geoip_country_name$geoip_country_code$geoip_continent_name$geoip_continent_code$geoip_postal_code$geoip_time_zone
You can also explicitly chose to enable or disable GeoIP for a single capture request like so:
Node.js
PostHog AI
client.capture({
distinctId: distinctId,
event: 'your_event',
disableGeoip: `true`,
})
Shutdown
You should call shutdown on your program's exit to exit cleanly:
Node.js
PostHog AI
// Stop pending pollers and flush any remaining events
await client.shutdown()
Debug mode
If you're not seeing the expected events being captured, the feature flags being evaluated, or the surveys being shown, you can enable debug mode to see what's happening.
You can enable debug mode by calling the debug() method in your code. This will enable verbose logs about the inner workings of the SDK.
Node.js
PostHog AI
client.debug()
Handling errors thrown by the SDK
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:
Node.js
PostHog AI
client.on("error", (err) => {
// Whatever handling you want
console.error("PostHog had an error!", err)
})
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:
Node.js
PostHog AI
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()
}
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 posthog-node and @posthog/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 posthog-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.
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:
- The minimum PostHog version requirement is 1.38
- The
callbackparameter passed as an optional last argument to most of the methods is no longer supported - The method signature for
isFeatureEnabledandgetFeatureFlagis slightly modified. See the above documentation for each method for more details. - For specific changes, see the CHANGELOG
Community questions
Ask a question
Was this page useful?
HelpfulCould be better