PostHog Node.js SDK

SDK Version:

PostHog

Initialization methods

PostHogpublic

Initialize a new PostHog client instance.

Parameters

NameType
apiKeystring

Your PostHog project API key

options?PostHogOptions

Configuration options for the client

Examples

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

Returns

Type
any

debugpublic

Enable or disable debug logging.

Parameters

NameType
enabled?boolean

Whether to enable debug logging

Examples

JavaScript
// Enable debug logging
client.debug(true)

Returns

Type
void

getLibraryVersionpublic

Get the library version from package.json.

Examples

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

Returns

Type
string

getPersistedPropertypublic

Get a persisted property value from memory storage.

Parameters

NameType
keyPostHogPersistedProperty

The property key to retrieve

Examples

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

Returns

Type
Union ofany
undefined

setPersistedPropertypublic

Set a persisted property value in memory storage.

Parameters

NameType
keyPostHogPersistedProperty

The property key to set

valueany | null

The value to store (null to remove)

Examples

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

Returns

Type
void

Capture methods

capturepublic

Capture an event manually.

Parameters

NameType
propsEventMessage

The event properties

Examples

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

Returns

Type
void

captureImmediatepublic

Capture an event immediately (synchronously).

Parameters

NameType
propsEventMessage

The event properties

Examples

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

Returns

Type
Promise<void>

Context methods

getContextpublic

Get the current context data.

Examples

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

Returns

Type
Union ofContextData
undefined

withContextpublic

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

NameType
dataPartial<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)

Examples

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

Returns

Type
T

Error tracking methods

captureExceptionpublic

Capture an error exception as an event.

Parameters

NameType
errorunknown

The error to capture

distinctId?string

Optional user distinct ID

additionalProperties?Record<string | number, any>

Optional additional properties to include

Examples

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

Returns

Type
void

captureExceptionImmediatepublic

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

Parameters

NameType
errorunknown

The error to capture

distinctId?string

Optional user distinct ID

additionalProperties?Record<string | number, any>

Optional additional properties to include

Examples

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

Returns

Type
Promise<void>

Feature flags methods

getAllFlagspublic

Get all feature flag values for a specific user.

Parameters

NameType
distinctIdstring

The user's distinct ID

options?{ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; disableGeoip?: boolean; flagKeys?: string[]; }

Optional configuration for flag evaluation

Examples

JavaScript
// 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' }

Returns

Type
Promise<Record<string, FeatureFlagValue>>

getAllFlagsAndPayloadspublic

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

Parameters

NameType
distinctIdstring

The user's distinct ID

options?{ groups?: Record<string, string>; personProperties?: Record<string, string>; groupProperties?: Record<string, Record<string, string>>; onlyEvaluateLocally?: boolean; disableGeoip?: boolean; flagKeys?: string[]; }

Optional configuration for flag evaluation

Examples

JavaScript
// 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)

Returns

Type
Promise<PostHogFlagsAndPayloadsResponse>

getFeatureFlagpublic

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

Parameters

NameType
keystring

The feature flag key

distinctIdstring

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

Examples

JavaScript
// 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
}

Returns

Type
Union ofPromise<FeatureFlagValue
undefined>

getFeatureFlagPayloadpublic

Get the payload for a feature flag.

Parameters

NameType
keystring

The feature flag key

distinctIdstring

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

Examples

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

Returns

Type
Union ofPromise<JsonType
undefined>

getRemoteConfigPayloadpublic

Get the remote config payload for a feature flag.

Parameters

NameType
flagKeystring

The feature flag key

Examples

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

Returns

Type
Union ofPromise<JsonType
undefined>

isFeatureEnabledpublic

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

Parameters

NameType
keystring

The feature flag key

distinctIdstring

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

Examples

JavaScript
// 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')
}

Returns

Type
Union ofPromise<boolean
undefined>

isLocalEvaluationReadypublic

Check if local evaluation of feature flags is ready.

Examples

JavaScript
// 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')
}

Returns

Type
boolean

reloadFeatureFlagspublic

Reload feature flag definitions from the server for local evaluation.

Examples

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

Returns

Type
Promise<void>

waitForLocalEvaluationReadypublic

Wait for local evaluation of feature flags to be ready.

Parameters

NameType
timeoutMs?number

Timeout in milliseconds (default: 30000)

Examples

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

Returns

Type
Promise<boolean>

Identification methods

aliaspublic

Create an alias to link two distinct IDs together.

Parameters

NameType
data{ distinctId: string; alias: string; disableGeoip?: boolean; }

The alias data containing distinctId and alias

Examples

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

Returns

Type
void

aliasImmediatepublic

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

Parameters

NameType
data{ distinctId: string; alias: string; disableGeoip?: boolean; }

The alias data containing distinctId and alias

Examples

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

Returns

Type
Promise<void>

getCustomUserAgentpublic

Get the custom user agent string for this client.

Examples

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

Returns

Type
string

groupIdentifypublic

Create or update a group and its properties.

Parameters

NameType
{ groupType, groupKey, properties, distinctId, disableGeoip }GroupIdentifyMessage

Examples

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

Returns

Type
void

identifypublic

Identify a user and set their properties.

Parameters

NameType
{ distinctId, properties, disableGeoip }IdentifyMessage

Examples

JavaScript
// Basic identify with properties
client.identify({
distinctId: 'user_123',
properties: {
name: 'John Doe',
email: 'john@example.com',
plan: 'premium'
}
})

Returns

Type
void

identifyImmediatepublic

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

Parameters

NameType
{ distinctId, properties, disableGeoip }IdentifyMessage

Examples

JavaScript
// Basic immediate identify
await client.identifyImmediate({
distinctId: 'user_123',
properties: {
name: 'John Doe',
email: 'john@example.com'
}
})

Returns

Type
Promise<void>

Privacy methods

disablepublic

Disable the PostHog client (opt-out).

Examples

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

Returns

Type
Promise<void>

enablepublic

Enable the PostHog client (opt-in).

Examples

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

Returns

Type
Promise<void>

Other methods

getLibraryIdpublic

Examples

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

Returns

Type
string

initializeContextpublic

Examples

JavaScript
// Generated example for initializeContext
posthog.initializeContext();

Returns

Type
PostHogContext

prepareEventMessagepublic

Parameters

NameType
propsEventMessage

Examples

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

Returns

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

Community questions

Questions about this page? or post a community question.