There are 2 steps to implement feature flags in Node:

### Step 1: Evaluate the feature flag value

#### Boolean feature flags

```node
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', isFeatureFlagEnabled)
}
```

#### Multivariate feature flags

```node
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', enabledVariant)
}
```

import IncludePropertyInEvents from "./include-feature-flag-property-in-backend-events.mdx" 

<IncludePropertyInEvents />

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`:

```node
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`

import NodeSetSendFeatureFlagsTrue from "./feature-flags-code-node-set-send-feature-flags-to-true.mdx" 

<NodeSetSendFeatureFlagsTrue />

### 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.

```node
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](/docs/product-analytics/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:

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

import NodeOverrideServerProperties from './override-server-properties/node.mdx'

<NodeOverrideServerProperties />

### 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.

```js
const client = new PostHog('<ph_project_api_key>', { 
        api_host: '<ph_client_api_host>',
        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:

```js
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
}
```


