Integration Javascript Node

PostHog Node.js SDK

SDK Version: 5.28.5

PostHog Node.js SDK allows you to capture events and send them to PostHog from your Node.js applications.

Categories

• Initialization

• Identification

• Capture

• Error tracking

• Privacy

• Feature flags

• Context

PostHog

Other methods

getLibraryId()

Release Tag: public

Returns

• string

Examples

// Generated example for getLibraryId
posthog.getLibraryId();

enterContext()

Release Tag: public

Set context without a callback wrapper. Uses AsyncLocalStorage.enterWith() to attach context to the current async execution context. The context lives until that async context ends. Must be called in the same async scope that makes PostHog calls. Calling this outside a request-scoped async context will leak context across unrelated work. Prefer withContext() when you can wrap code in a callback — it creates an isolated scope that cleans up automatically.

Parameters

• data (Partial<ContextData>) - Context data to apply (distinctId, sessionId, properties)

• options? (ContextOptions) - Context options (fresh: true to start with clean context instead of inheriting)

Returns

• void

Examples

// Generated example for enterContext
posthog.enterContext();

flush()

Release Tag: public

Returns

• Promise<void>

Examples

// Generated example for flush
posthog.flush();

prepareEventMessage()

Release Tag: public

Parameters

• props (EventMessage)

Returns

• Promise<{ distinctId: string; event: string; properties: PostHogEventProperties; options: PostHogCaptureOptions; }>

Examples

// Generated example for prepareEventMessage
posthog.prepareEventMessage();

fetch()

Release Tag: public

Parameters

• url (string)

• options (PostHogFetchOptions)

Returns

• Promise<PostHogFetchResponse>

Examples

// Generated example for fetch
posthog.fetch();

getSurveysStateless()

Release Tag: public

• ** SURVEYS *

Returns

• Promise<SurveyResponse['surveys']>

Examples

// Generated example for getSurveysStateless
posthog.getSurveysStateless();

on()

Release Tag: public

Parameters

• event (string)

• cb ((...args: any[]) => void)

Returns

• () => void

Examples

// Generated example for on
posthog.on();

optIn()

Release Tag: public

Returns

• Promise<void>

Examples

// Generated example for optIn
posthog.optIn();

optOut()

Release Tag: public

Returns

• Promise<void>

Examples

// Generated example for optOut
posthog.optOut();

register()

Release Tag: public

Parameters

• properties (PostHogEventProperties)

Returns

• Promise<void>

Examples

// Generated example for register
posthog.register();

unregister()

Release Tag: public

Parameters

• property (string)

Returns

• Promise<void>

Examples

// Generated example for unregister
posthog.unregister();

Initialization methods

PostHog()

Release Tag: public

Initialize a new PostHog client instance.

Parameters

• apiKey (string) - Your PostHog project API key

• options? (PostHogOptions) - Configuration options for the client

Returns

• any

Examples

Basic initialization

// Basic initialization
const client = new PostHogBackendClient(
  'your-api-key',
  { host: 'https://app.posthog.com' }
)

With personal API key

// With personal API key
const client = new PostHogBackendClient(
  'your-api-key',
  {
    host: 'https://app.posthog.com',
    personalApiKey: 'your-personal-api-key'
  }
)

debug()

Release Tag: public

Enable or disable debug logging.

Parameters

• enabled? (boolean) - Whether to enable debug logging

Returns

• void

Examples

Enable debug logging

// Enable debug logging
client.debug(true)

Disable debug logging

// Disable debug logging
client.debug(false)

getLibraryVersion()

Release Tag: public

Get the library version from package.json.

Returns

• string

Examples

// Get version
const version = client.getLibraryVersion()
console.log(`Using PostHog SDK version: ${version}`)

getPersistedProperty()

Release Tag: public

Get a persisted property value from memory storage.

Parameters

• key (PostHogPersistedProperty) - The property key to retrieve

Returns

Union of:

• any

• undefined

Examples

Get user ID

// Get user ID
const userId = client.getPersistedProperty('userId')

Get session ID

// Get session ID
const sessionId = client.getPersistedProperty('sessionId')

setPersistedProperty()

Release Tag: public

Set a persisted property value in memory storage.

Parameters

• key (PostHogPersistedProperty) - The property key to set

• value (any | null) - The value to store (null to remove)

Returns

• void

Examples

Set user ID

// Set user ID
client.setPersistedProperty('userId', 'user_123')

Set session ID

// Set session ID
client.setPersistedProperty('sessionId', 'session_456')

shutdown()

Release Tag: public

Shuts down the PostHog instance and ensures all events are sent. Call shutdown() once before the process exits to ensure that all events have been sent and all promises have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it. Use flush() for per-request cleanup instead.

Parameters

• shutdownTimeoutMs? (number) - Maximum time to wait for shutdown in milliseconds

Returns

• Promise<void>

Examples

// shutdown before process exit
process.on('SIGINT', async () => {
  await posthog.shutdown()
  process.exit(0)
})

Identification methods

alias()

Release Tag: public

Create an alias to link two distinct IDs together.

Parameters

• data ({ distinctId: string; alias: string; disableGeoip?: boolean; }) - The alias data containing distinctId and alias

Returns

• void

Examples

// Link an anonymous user to an identified user
client.alias({
  distinctId: 'anonymous_123',
  alias: 'user_456'
})

aliasImmediate()

Release Tag: public

Create an alias to link two distinct IDs together immediately (synchronously).

Parameters

• data ({ distinctId: string; alias: string; disableGeoip?: boolean; }) - The alias data containing distinctId and alias

Returns

• Promise<void>

Examples

// Link an anonymous user to an identified user immediately
await client.aliasImmediate({
  distinctId: 'anonymous_123',
  alias: 'user_456'
})

getCustomUserAgent()

Release Tag: public

Get the custom user agent string for this client.

Returns

• string

Examples

// Get user agent
const userAgent = client.getCustomUserAgent()
// Returns: "posthog-node/5.7.0"

groupIdentify()

Release Tag: public

Create or update a group and its properties.

Parameters

• { groupType, groupKey, properties, distinctId, disableGeoip } (GroupIdentifyMessage)

Returns

• void

Examples

Create a company group

// Create a company group
client.groupIdentify({
  groupType: 'company',
  groupKey: 'acme-corp',
  properties: {
    name: 'Acme Corporation',
    industry: 'Technology',
    employee_count: 500
  },
  distinctId: 'user_123'
})

Update organization properties

// Update organization properties
client.groupIdentify({
  groupType: 'organization',
  groupKey: 'org-456',
  properties: {
    plan: 'enterprise',
    region: 'US-West'
  }
})

identify()

Release Tag: public

Identify a user and set their properties.

Parameters

• { distinctId, properties, disableGeoip } (IdentifyMessage)

Returns

• void

Examples

Basic identify with properties

// Basic identify with properties
client.identify({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: '[email protected]',
    plan: 'premium'
  }
})

Using $set and $set_once

// Using $set and $set_once
client.identify({
  distinctId: 'user_123',
  properties: {
    $set: { name: 'John Doe', email: '[email protected]' },
    $set_once: { first_login: new Date().toISOString() }
    $anon_distinct_id: 'anonymous_user_456'
  }
})

identifyImmediate()

Release Tag: public

Identify a user and set their properties immediately (synchronously).

Parameters

• { distinctId, properties, disableGeoip } (IdentifyMessage)

Returns

• Promise<void>

Examples

// Basic immediate identify
await client.identifyImmediate({
  distinctId: 'user_123',
  properties: {
    name: 'John Doe',
    email: '[email protected]'
  }
})

Capture methods

capture()

Release Tag: public

Capture an event manually.

Parameters

• props (EventMessage) - The event properties

Returns

• void

Examples

// Basic capture
client.capture({
  distinctId: 'user_123',
  event: 'button_clicked',
  properties: { button_color: 'red' }
})

captureImmediate()

Release Tag: public

Capture an event immediately (synchronously).

Parameters

• props (EventMessage) - The event properties

Returns

• Promise<void>

Examples

Basic immediate capture

// Basic immediate capture
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'button_clicked',
  properties: { button_color: 'red' }
})

With feature flags

// With feature flags
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'user_action',
  sendFeatureFlags: true
})

With custom feature flags options

// With custom feature flags options
await client.captureImmediate({
  distinctId: 'user_123',
  event: 'user_action',
  sendFeatureFlags: {
    onlyEvaluateLocally: true,
    personProperties: { plan: 'premium' },
    groupProperties: { org: { tier: 'enterprise' } }
    flagKeys: ['flag1', 'flag2']
  }
})

Error tracking methods

captureException()

Release Tag: public

Capture an error exception as an event.

Parameters

• error (unknown) - The error to capture

• distinctId? (string) - Optional user distinct ID

• additionalProperties? (Record<string | number, any>) - Optional additional properties to include

• uuid? (EventMessage['uuid'])

Returns

• void

Examples

Capture an error with user ID

// Capture an error with user ID
try {
  // Some risky operation
  riskyOperation()
} catch (error) {
  client.captureException(error, 'user_123')
}

Capture with additional properties

// Capture with additional properties
try {
  apiCall()
} catch (error) {
  client.captureException(error, 'user_123', {
    endpoint: '/api/users',
    method: 'POST',
    status_code: 500
  })
}

captureExceptionImmediate()

Release Tag: public

Capture an error exception as an event immediately (synchronously).

Parameters

• error (unknown) - The error to capture

• distinctId? (string) - Optional user distinct ID

• additionalProperties? (Record<string | number, any>) - Optional additional properties to include

Returns

• Promise<void>

Examples

Capture an error immediately with user ID

// Capture an error immediately with user ID
try {
  // Some risky operation
  riskyOperation()
} catch (error) {
  await client.captureExceptionImmediate(error, 'user_123')
}

Capture with additional properties

// Capture with additional properties
try {
  apiCall()
} catch (error) {
  await client.captureExceptionImmediate(error, 'user_123', {
    endpoint: '/api/users',
    method: 'POST',
    status_code: 500
  })
}

Privacy methods

disable()

Release Tag: public

Disable the PostHog client (opt-out).

Returns

• Promise<void>

Examples

// Disable client
await client.disable()
// Client is now disabled and will not capture events

enable()

Release Tag: public

Enable the PostHog client (opt-in).

Returns

• Promise<void>

Examples

// Enable client
await client.enable()
// Client is now enabled and will capture events

Feature flags methods

getAllFlags()

Release Tag: public

Get all feature flag values for a specific user.

Parameters

• options? (AllFlagsOptions) - Optional configuration for flag evaluation

Returns

• Promise<Record<string, FeatureFlagValue>>

Examples

Get all flags for a user

// Get all flags for a user
const allFlags = await client.getAllFlags('user_123')
console.log('User flags:', allFlags)
// Output: { 'flag-1': 'variant-a', 'flag-2': false, 'flag-3': 'variant-b' }

With specific flag keys

// With specific flag keys
const specificFlags = await client.getAllFlags('user_123', {
  flagKeys: ['flag-1', 'flag-2']
})

With groups and properties

// With groups and properties
const orgFlags = await client.getAllFlags('user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

getAllFlagsAndPayloads()

Release Tag: public

Get all feature flag values and payloads for a specific user.

Parameters

• options? (AllFlagsOptions) - Optional configuration for flag evaluation

Returns

• Promise<PostHogFlagsAndPayloadsResponse>

Examples

Get all flags and payloads for a user

// Get all flags and payloads for a user
const result = await client.getAllFlagsAndPayloads('user_123')
console.log('Flags:', result.featureFlags)
console.log('Payloads:', result.featureFlagPayloads)

With specific flag keys

// With specific flag keys
const result = await client.getAllFlagsAndPayloads('user_123', {
  flagKeys: ['flag-1', 'flag-2']
})

Only evaluate locally

// Only evaluate locally
const result = await client.getAllFlagsAndPayloads('user_123', {
  onlyEvaluateLocally: true
})

getFeatureFlag()

Release Tag: public

Get the value of a feature flag for a specific user.

Parameters

• key (string) - The feature flag key

• distinctId (string) - The user's distinct ID

• options? ({ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<FeatureFlagValue

• undefined>

Examples

Basic feature flag check

// Basic feature flag check
const flagValue = await client.getFeatureFlag('new-feature', 'user_123')
if (flagValue === 'variant-a') {
  // Show variant A
} else if (flagValue === 'variant-b') {
  // Show variant B
} else {
  // Flag is disabled or not found
}

With groups and properties

// With groups and properties
const flagValue = await client.getFeatureFlag('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' },
  groupProperties: { organization: { tier: 'premium' } }
})

Only evaluate locally

// Only evaluate locally
const flagValue = await client.getFeatureFlag('local-flag', 'user_123', {
  onlyEvaluateLocally: true
})

getFeatureFlagPayload()

Release Tag: public

Get the payload for a feature flag.

Parameters

• key (string) - The feature flag key

• distinctId (string) - The user's distinct ID

• matchValue? (FeatureFlagValue) - Optional match value to get payload for

• options? ({ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<JsonType

• undefined>

Examples

Get payload for a feature flag

// Get payload for a feature flag
const payload = await client.getFeatureFlagPayload('flag-key', 'user_123')
if (payload) {
  console.log('Flag payload:', payload)
}

Get payload with specific match value

// Get payload with specific match value
const payload = await client.getFeatureFlagPayload('flag-key', 'user_123', 'variant-a')

With groups and properties

// With groups and properties
const payload = await client.getFeatureFlagPayload('org-flag', 'user_123', undefined, {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

getFeatureFlagResult()

Release Tag: public

Get the result of evaluating a feature flag, including its value and payload. This is more efficient than calling getFeatureFlag and getFeatureFlagPayload separately when you need both.

Parameters

• key (string) - The feature flag key

• options? (FlagEvaluationOptions) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<FeatureFlagResult

• undefined>

Examples

Get flag result

// Get flag result
const result = await client.getFeatureFlagResult('my-flag', 'user_123')
if (result) {
  console.log('Flag enabled:', result.enabled)
  console.log('Variant:', result.variant)
  console.log('Payload:', result.payload)
}

With groups and properties

// With groups and properties
const result = await client.getFeatureFlagResult('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

getRemoteConfigPayload()

Release Tag: public

Get the remote config payload for a feature flag.

Parameters

• flagKey (string) - The feature flag key

Returns

Union of:

• Promise<JsonType

• undefined>

Examples

// Get remote config payload
const payload = await client.getRemoteConfigPayload('flag-key')
if (payload) {
  console.log('Remote config payload:', payload)
}

isFeatureEnabled()

Release Tag: public

Check if a feature flag is enabled for a specific user.

Parameters

• key (string) - The feature flag key

• distinctId (string) - The user's distinct ID

• options? ({ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; sendFeatureFlagEvents?: boolean; disableGeoip?: boolean; }) - Optional configuration for flag evaluation

Returns

Union of:

• Promise<boolean

• undefined>

Examples

Basic feature flag check

// Basic feature flag check
const isEnabled = await client.isFeatureEnabled('new-feature', 'user_123')
if (isEnabled) {
  // Feature is enabled
  console.log('New feature is active')
} else {
  // Feature is disabled
  console.log('New feature is not active')
}

With groups and properties

// With groups and properties
const isEnabled = await client.isFeatureEnabled('org-feature', 'user_123', {
  groups: { organization: 'acme-corp' },
  personProperties: { plan: 'enterprise' }
})

isLocalEvaluationReady()

Release Tag: public

Check if local evaluation of feature flags is ready.

Returns

• boolean

Examples

// Check if ready
if (client.isLocalEvaluationReady()) {
  // Local evaluation is ready, can evaluate flags locally
  const flag = await client.getFeatureFlag('flag-key', 'user_123')
} else {
  // Local evaluation not ready, will use remote evaluation
  const flag = await client.getFeatureFlag('flag-key', 'user_123')
}

overrideFeatureFlags()

Release Tag: public

Override feature flags locally. Useful for testing and local development. Overridden flags take precedence over both local evaluation and remote evaluation.

Parameters

• overrides (OverrideFeatureFlagsOptions) - Flag overrides configuration

Returns

• void

Examples

// Clear all overrides
client.overrideFeatureFlags(false)

// Enable a list of flags (sets them to true)
client.overrideFeatureFlags(['flag-a', 'flag-b'])

// Set specific flag values/variants
client.overrideFeatureFlags({ 'my-flag': 'variant-a', 'other-flag': true })

// Set both flags and payloads
client.overrideFeatureFlags({
  flags: { 'my-flag': 'variant-a' },
  payloads: { 'my-flag': { discount: 20 } }
})

reloadFeatureFlags()

Release Tag: public

Reload feature flag definitions from the server for local evaluation.

Returns

• Promise<void>

Examples

Force reload of feature flags

// Force reload of feature flags
await client.reloadFeatureFlags()
console.log('Feature flags reloaded')

Reload before checking a specific flag

// Reload before checking a specific flag
await client.reloadFeatureFlags()
const flag = await client.getFeatureFlag('flag-key', 'user_123')

waitForLocalEvaluationReady()

Release Tag: public

Wait for local evaluation of feature flags to be ready.

Parameters

• timeoutMs? (number) - Timeout in milliseconds (default: 30000)

Returns

• Promise<boolean>

Examples

Wait for local evaluation

// Wait for local evaluation
const isReady = await client.waitForLocalEvaluationReady()
if (isReady) {
  console.log('Local evaluation is ready')
} else {
  console.log('Local evaluation timed out')
}

Wait with custom timeout

// Wait with custom timeout
const isReady = await client.waitForLocalEvaluationReady(10000) // 10 seconds

Context methods

getContext()

Release Tag: public

Get the current context data.

Returns

Union of:

• ContextData

• undefined

Examples

// Get current context within a withContext block
posthog.withContext({ distinctId: 'user_123' }, () => {
  const context = posthog.getContext()
  console.log(context?.distinctId) // 'user_123'
})

withContext()

Release Tag: public

Run a function with specific context that will be applied to all events captured within that context. It propagates the context to all subsequent calls down the call stack. Context properties like tags and sessionId will be automatically attached to all events. By default, nested contexts inherit from parent contexts. Use { fresh: true } to start with a clean context.

Parameters

• data (Partial<ContextData>) - Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)

• fn (() => T) - Function to run with the context

• options? (ContextOptions) - Context options (fresh: true to start with clean context instead of inheriting)

Returns

• T

Examples

posthog.withContext({ distinctId: 'user_123' }, () => {
  posthog.capture({ event: 'button clicked' })
})