AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

integration-javascript_node

PostHog integration for server-side Node.js applications using posthog-node

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--integration-javascript_node at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 8

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:

  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:

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:

  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

Community questions

Ask a question

Was this page useful?

HelpfulCould be better