@posthog/react 1.2.2 → 1.2.3

package/src/components/index.ts

@@ -0,0 +1,6 @@
+export * from './PostHogFeature'
+export {
+    PostHogErrorBoundary,
+    PostHogErrorBoundaryProps,
+    PostHogErrorBoundaryFallbackProps,
+} from './PostHogErrorBoundary'

package/src/context/PostHogContext.ts

@@ -0,0 +1,6 @@
+import posthogJs from 'posthog-js'
+import { createContext } from 'react'
+
+export type PostHog = typeof posthogJs
+
+export const PostHogContext = createContext<{ client: PostHog }>({ client: posthogJs })

package/src/context/PostHogProvider.tsx

@@ -0,0 +1,128 @@
+/* eslint-disable no-console */
+import posthogJs, { PostHogConfig } from 'posthog-js'
+
+import React, { useEffect, useMemo, useRef } from 'react'
+import { PostHog, PostHogContext } from './PostHogContext'
+import { isDeepEqual } from '../utils/object-utils'
+
+interface PreviousInitialization {
+    apiKey: string
+    options: Partial<PostHogConfig>
+}
+
+type WithOptionalChildren<T> = T & { children?: React.ReactNode | undefined }
+
+/**
+ * Props for the PostHogProvider component.
+ * This is a discriminated union type that ensures mutually exclusive props:
+ *
+ * - If `client` is provided, `apiKey` and `options` must not be provided
+ * - If `apiKey` is provided, `client` must not be provided, and `options` is optional
+ */
+type PostHogProviderProps =
+    | { client: PostHog; apiKey?: never; options?: never }
+    | { apiKey: string; options?: Partial<PostHogConfig>; client?: never }
+
+/**
+ * PostHogProvider is a React context provider for PostHog analytics.
+ * It can be initialized in two mutually exclusive ways:
+ *
+ * 1. By providing an existing PostHog `client` instance
+ * 2. By providing an `apiKey` (and optionally `options`) to create a new client
+ *
+ * These initialization methods are mutually exclusive - you must use one or the other,
+ * but not both simultaneously.
+ *
+ * We strongly suggest you memoize the `options` object to ensure that you don't
+ * accidentally trigger unnecessary re-renders. We'll properly detect if the options
+ * have changed and only call `posthogJs.set_config` if they have, but it's better to
+ * avoid unnecessary re-renders in the first place.
+ */
+export function PostHogProvider({ children, client, apiKey, options }: WithOptionalChildren<PostHogProviderProps>) {
+    // Used to detect if the client was already initialized
+    // This is used to prevent double initialization when running under React.StrictMode
+    // We're not storing a simple boolean here because we want to be able to detect if the
+    // apiKey or options have changed.
+    const previousInitializationRef = useRef<PreviousInitialization | null>(null)
+
+    const posthog = useMemo(() => {
+        if (client) {
+            if (apiKey) {
+                console.warn(
+                    '[PostHog.js] You have provided both `client` and `apiKey` to `PostHogProvider`. `apiKey` will be ignored in favour of `client`.'
+                )
+            }
+            if (options) {
+                console.warn(
+                    '[PostHog.js] You have provided both `client` and `options` to `PostHogProvider`. `options` will be ignored in favour of `client`.'
+                )
+            }
+            return client
+        }
+
+        if (apiKey) {
+            // return the global client, we'll initialize it in the useEffect
+            return posthogJs
+        }
+
+        console.warn(
+            '[PostHog.js] No `apiKey` or `client` were provided to `PostHogProvider`. Using default global `window.posthog` instance. You must initialize it manually. This is not recommended behavior.'
+        )
+        return posthogJs
+    }, [client, apiKey, JSON.stringify(options)]) // Stringify options to be a stable reference
+
+    // TRICKY: The init needs to happen in a useEffect rather than useMemo, as useEffect does not happen during SSR. Otherwise
+    // we'd end up trying to call posthogJs.init() on the server, which can cause issues around hydration and double-init.
+    useEffect(() => {
+        if (client) {
+            // if the user has passed their own client, assume they will also handle calling init().
+            return
+        }
+        const previousInitialization = previousInitializationRef.current
+
+        if (!previousInitialization) {
+            // If it's the first time running this, but it has been loaded elsewhere, warn the user about it.
+            if (posthogJs.__loaded) {
+                console.warn('[PostHog.js] `posthog` was already loaded elsewhere. This may cause issues.')
+            }
+
+            // Init global client
+            posthogJs.init(apiKey, options)
+
+            // Keep track of whether the client was already initialized
+            // This is used to prevent double initialization when running under React.StrictMode, and to know when options change
+            previousInitializationRef.current = {
+                apiKey: apiKey,
+                options: options ?? {},
+            }
+        } else {
+            // If the client was already initialized, we might still end up running the effect again for a few reasons:
+            // * someone is developing locally under `React.StrictMode`
+            // * the config has changed
+            // * the apiKey has changed (not supported!)
+            //
+            // Changing the apiKey isn't well supported and we'll simply log a message suggesting them
+            // to take control of the `client` initialization themselves. This is tricky to handle
+            // ourselves because we wouldn't know if we should call `.reset()` or not, for example.
+            if (apiKey !== previousInitialization.apiKey) {
+                console.warn(
+                    "[PostHog.js] You have provided a different `apiKey` to `PostHogProvider` than the one that was already initialized. This is not supported by our provider and we'll keep using the previous key. If you need to toggle between API Keys you need to control the `client` yourself and pass it in as a prop rather than an `apiKey` prop."
+                )
+            }
+
+            // Changing options is better supported because we can just call `posthogJs.set_config(options)`
+            // and they'll be good to go with their new config. The SDK will know how to handle the changes.
+            if (options && !isDeepEqual(options, previousInitialization.options)) {
+                posthogJs.set_config(options)
+            }
+
+            // Keep track of the possibly-new set of apiKey and options
+            previousInitializationRef.current = {
+                apiKey: apiKey,
+                options: options ?? {},
+            }
+        }
+    }, [client, apiKey, JSON.stringify(options)]) // Stringify options to be a stable reference
+
+    return <PostHogContext.Provider value={{ client: posthog }}>{children}</PostHogContext.Provider>
+}

package/src/context/__tests__/PostHogContext.test.jsx

@@ -0,0 +1,34 @@
+import * as React from 'react'
+import { render } from '@testing-library/react'
+import { PostHogProvider } from '..'
+
+describe('PostHogContext component', () => {
+    given(
+        'render',
+        () => () =>
+            render(
+                <PostHogProvider client={given.posthog}>
+                    <div>Hello</div>
+                </PostHogProvider>
+            )
+    )
+    given('posthog', () => ({}))
+
+    it('should return a client instance from the context if available', () => {
+        given.render()
+    })
+
+    it("should not throw error if a client instance can't be found in the context", () => {
+        given('posthog', () => undefined) // it might not exist in SSR for example
+
+        // eslint-disable-next-line no-console
+        console.warn = jest.fn()
+
+        expect(() => given.render()).not.toThrow()
+
+        // eslint-disable-next-line no-console
+        expect(console.warn).toHaveBeenCalledWith(
+            '[PostHog.js] No `apiKey` or `client` were provided to `PostHogProvider`. Using default global `window.posthog` instance. You must initialize it manually. This is not recommended behavior.'
+        )
+    })
+})

package/src/context/__tests__/PostHogProvider.test.jsx

@@ -0,0 +1,131 @@
+import * as React from 'react'
+import { render, act } from '@testing-library/react'
+import { PostHogProvider } from '..'
+import posthogJs from 'posthog-js'
+
+// Mock posthog-js
+jest.mock('posthog-js', () => ({
+    __esModule: true,
+    default: {
+        init: jest.fn(),
+        set_config: jest.fn(),
+        __loaded: false,
+    },
+}))
+
+describe('PostHogProvider component', () => {
+    it('should render children components', () => {
+        const posthog = {}
+        const { getByText } = render(
+            <PostHogProvider client={posthog}>
+                <div>Test</div>
+            </PostHogProvider>
+        )
+        expect(getByText('Test')).toBeTruthy()
+    })
+
+    describe('when using apiKey initialization', () => {
+        const apiKey = 'test-api-key'
+        const initialOptions = { api_host: 'https://app.posthog.com' }
+        const updatedOptions = { api_host: 'https://eu.posthog.com' }
+
+        beforeEach(() => {
+            jest.clearAllMocks()
+        })
+
+        it('should call set_config when options change', () => {
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new options
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={apiKey} options={updatedOptions}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should call set_config with new options
+            expect(posthogJs.set_config).toHaveBeenCalledWith(updatedOptions)
+        })
+
+        it('should NOT call set_config when we pass new options that are the same as the previous options', () => {
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new options
+            const sameOptionsButDifferentReference = { ...initialOptions }
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={apiKey} options={sameOptionsButDifferentReference}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should NOT call set_config
+            expect(posthogJs.set_config).not.toHaveBeenCalled()
+        })
+
+        it('should warn when attempting to change apiKey', () => {
+            const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+            const newApiKey = 'different-api-key'
+
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new apiKey
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={newApiKey} options={initialOptions}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should warn about apiKey change
+            expect(consoleSpy).toHaveBeenCalledWith(
+                expect.stringContaining('You have provided a different `apiKey` to `PostHogProvider`')
+            )
+
+            consoleSpy.mockRestore()
+        })
+
+        it('warns if posthogJs has been loaded elsewhere', () => {
+            posthogJs.__loaded = true // Pretend it's initialized
+
+            const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+            render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            expect(consoleSpy).toHaveBeenCalledWith(
+                expect.stringContaining('`posthog` was already loaded elsewhere. This may cause issues.')
+            )
+
+            consoleSpy.mockRestore()
+            posthogJs.__loaded = false
+        })
+    })
+})

package/src/context/index.ts

@@ -0,0 +1,2 @@
+export * from './PostHogContext'
+export * from './PostHogProvider'

package/src/helpers/error-helpers.ts

@@ -0,0 +1,15 @@
+import type { ErrorInfo } from 'react'
+import { PostHog } from '../context'
+import { CaptureResult } from 'posthog-js'
+
+export const setupReactErrorHandler = (
+    client: PostHog,
+    callback?: (event: CaptureResult | undefined, error: any, errorInfo: ErrorInfo) => void
+) => {
+    return (error: any, errorInfo: ErrorInfo): void => {
+        const event = client.captureException(error)
+        if (callback) {
+            callback(event, error, errorInfo)
+        }
+    }
+}

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './error-helpers'

package/src/hooks/__tests__/featureFlags.test.jsx

@@ -0,0 +1,93 @@
+import * as React from 'react'
+import { renderHook } from '@testing-library/react-hooks'
+import { PostHogProvider } from '../../context'
+import { useFeatureFlagPayload, useFeatureFlagVariantKey, useFeatureFlagEnabled, useActiveFeatureFlags } from '../index'
+
+jest.useFakeTimers()
+
+const ACTIVE_FEATURE_FLAGS = ['example_feature_true', 'multivariate_feature', 'example_feature_payload']
+
+const FEATURE_FLAG_STATUS = {
+    example_feature_true: true,
+    example_feature_false: false,
+    multivariate_feature: 'string-value',
+    example_feature_payload: 'test',
+}
+
+const FEATURE_FLAG_PAYLOADS = {
+    example_feature_payload: {
+        id: 1,
+        name: 'example_feature_1_payload',
+        key: 'example_feature_1_payload',
+    },
+}
+
+describe('useFeatureFlagPayload hook', () => {
+    given('renderProvider', () => ({ children }) => (
+        <PostHogProvider client={given.posthog}>{children}</PostHogProvider>
+    ))
+
+    given('posthog', () => ({
+        isFeatureEnabled: (flag) => !!FEATURE_FLAG_STATUS[flag],
+        getFeatureFlag: (flag) => FEATURE_FLAG_STATUS[flag],
+        getFeatureFlagPayload: (flag) => FEATURE_FLAG_PAYLOADS[flag],
+        onFeatureFlags: (callback) => {
+            const activeFlags = []
+            for (const flag in FEATURE_FLAG_STATUS) {
+                if (FEATURE_FLAG_STATUS[flag]) {
+                    activeFlags.push(flag)
+                }
+            }
+            callback(activeFlags)
+            return () => {}
+        },
+        featureFlags: {
+            getFlags: () => ACTIVE_FEATURE_FLAGS,
+        },
+    }))
+
+    it.each([
+        ['example_feature_true', true],
+        ['example_feature_false', false],
+        ['missing', false],
+        ['multivariate_feature', true],
+        ['example_feature_payload', true],
+    ])('should get the boolean feature flag', (flag, expected) => {
+        let { result } = renderHook(() => useFeatureFlagEnabled(flag), {
+            wrapper: given.renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+
+    it.each([
+        ['example_feature_true', undefined],
+        ['example_feature_false', undefined],
+        ['missing', undefined],
+        ['multivariate_feature', undefined],
+        ['example_feature_payload', FEATURE_FLAG_PAYLOADS.example_feature_payload],
+    ])('should get the payload feature flag', (flag, expected) => {
+        let { result } = renderHook(() => useFeatureFlagPayload(flag), {
+            wrapper: given.renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+
+    it('should return the active feature flags', () => {
+        let { result } = renderHook(() => useActiveFeatureFlags(), {
+            wrapper: given.renderProvider,
+        })
+        expect(result.current).toEqual(['example_feature_true', 'multivariate_feature', 'example_feature_payload'])
+    })
+
+    it.each([
+        ['example_feature_true', true],
+        ['example_feature_false', false],
+        ['missing', undefined],
+        ['multivariate_feature', 'string-value'],
+    ])('should get the feature flag variant key', (flag, expected) => {
+        let { result } = renderHook(() => useFeatureFlagVariantKey(flag), {
+            wrapper: given.renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+})

package/src/hooks/__tests__/usePostHog.test.jsx

@@ -0,0 +1,23 @@
+import * as React from 'react'
+import { renderHook } from '@testing-library/react-hooks'
+import { PostHogProvider } from '../../context'
+import { usePostHog } from '..'
+
+jest.useFakeTimers()
+
+const posthog = { posthog_client: true }
+
+describe('usePostHog hook', () => {
+    given('renderProvider', () => ({ children }) => (
+        <PostHogProvider client={given.posthog}>{children}</PostHogProvider>
+    ))
+
+    given('posthog', () => posthog)
+
+    it('should return the client', () => {
+        let { result } = renderHook(() => usePostHog(), {
+            wrapper: given.renderProvider,
+        })
+        expect(result.current).toEqual(posthog)
+    })
+})

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export * from './useFeatureFlagEnabled'
+export * from './useFeatureFlagPayload'
+export * from './useActiveFeatureFlags'
+export * from './useFeatureFlagVariantKey'
+export * from './usePostHog'

package/src/hooks/useActiveFeatureFlags.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react'
+import { usePostHog } from './usePostHog'
+
+export function useActiveFeatureFlags(): string[] {
+    const client = usePostHog()
+
+    const [featureFlags, setFeatureFlags] = useState<string[]>(() => client.featureFlags.getFlags())
+
+    useEffect(() => {
+        return client.onFeatureFlags((flags) => {
+            setFeatureFlags(flags)
+        })
+    }, [client])
+
+    return featureFlags
+}

package/src/hooks/useFeatureFlagEnabled.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from 'react'
+import { usePostHog } from './usePostHog'
+
+export function useFeatureFlagEnabled(flag: string): boolean | undefined {
+    const client = usePostHog()
+
+    const [featureEnabled, setFeatureEnabled] = useState<boolean | undefined>(() => client.isFeatureEnabled(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureEnabled(client.isFeatureEnabled(flag))
+        })
+    }, [client, flag])
+
+    return featureEnabled
+}

package/src/hooks/useFeatureFlagPayload.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react'
+import { JsonType } from 'posthog-js'
+import { usePostHog } from './usePostHog'
+
+export function useFeatureFlagPayload(flag: string): JsonType {
+    const client = usePostHog()
+
+    const [featureFlagPayload, setFeatureFlagPayload] = useState<JsonType>(() => client.getFeatureFlagPayload(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureFlagPayload(client.getFeatureFlagPayload(flag))
+        })
+    }, [client, flag])
+
+    return featureFlagPayload
+}

package/src/hooks/useFeatureFlagVariantKey.ts

@@ -0,0 +1,18 @@
+import { useEffect, useState } from 'react'
+import { usePostHog } from './usePostHog'
+
+export function useFeatureFlagVariantKey(flag: string): string | boolean | undefined {
+    const client = usePostHog()
+
+    const [featureFlagVariantKey, setFeatureFlagVariantKey] = useState<string | boolean | undefined>(() =>
+        client.getFeatureFlag(flag)
+    )
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureFlagVariantKey(client.getFeatureFlag(flag))
+        })
+    }, [client, flag])
+
+    return featureFlagVariantKey
+}

package/src/hooks/usePostHog.ts

@@ -0,0 +1,7 @@
+import { useContext } from 'react'
+import { PostHog, PostHogContext } from '../context'
+
+export const usePostHog = (): PostHog => {
+    const { client } = useContext(PostHogContext)
+    return client
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './context'
+export * from './hooks'
+export * from './components'
+export * from './helpers'

package/src/utils/__tests__/object-utils.test.ts

@@ -0,0 +1,42 @@
+import { isDeepEqual } from '../object-utils'
+
+const circularArray1: any[] = []
+circularArray1.push(circularArray1)
+const circularArray2: any[] = []
+circularArray2.push(circularArray2)
+
+function f1() {}
+function f2() {}
+
+describe('object-utils', () => {
+    describe('isDeepEqual', () => {
+        it.each([
+            [true, { a: 1, b: 2 }, { a: 1, b: 2 }],
+            [true, { a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }],
+            [false, { a: 1, b: 2 }, { a: 1, b: 3 }],
+            [false, { a: 1, b: 2 }, { a: 1 }],
+            [true, 'a', 'a'],
+            [false, 'a', 'b'],
+            [false, 1, 2],
+            [true, 0, -0],
+            [false, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY],
+            [false, 1, '1'],
+            [false, Number.NaN, Number.NaN],
+            [true, null, null],
+            [false, undefined, null],
+            [true, [], []],
+            [true, [[[[]]]], [[[[]]]]],
+            [false, [[[[]]]], [[[[[]]]]]],
+            [true, [1, 2, 3], [1, 2, 3]],
+            [false, [1, 2, 3], [1, 2, 4]],
+            [true, { a: circularArray1 }, { a: circularArray1 }],
+            [true, { a: circularArray1 }, { a: circularArray2 }],
+            [true, circularArray1, [circularArray1]],
+            [true, f1, f1],
+            [false, f1, f2],
+        ])('returns %s for %s and %s', (expected, obj1, obj2) => {
+            expect(isDeepEqual(obj1, obj2)).toBe(expected)
+            expect(isDeepEqual(obj2, obj1)).toBe(expected)
+        })
+    })
+})

package/src/utils/object-utils.ts

@@ -0,0 +1,36 @@
+// Deeply compares two objects for equality.
+// Use a WeakMap to keep track of visited objects to avoid infinite recursion.
+// WeakMap is supported in IE11, see https://caniuse.com/?search=JavaScript%20WeakMap
+
+export function isDeepEqual(obj1: any, obj2: any, visited = new WeakMap()): boolean {
+    if (obj1 === obj2) {
+        return true
+    }
+
+    if (typeof obj1 !== 'object' || obj1 === null || typeof obj2 !== 'object' || obj2 === null) {
+        return false
+    }
+
+    if (visited.has(obj1) && visited.get(obj1) === obj2) {
+        return true
+    }
+    visited.set(obj1, obj2)
+
+    const keys1 = Object.keys(obj1)
+    const keys2 = Object.keys(obj2)
+
+    if (keys1.length !== keys2.length) {
+        return false
+    }
+
+    for (const key of keys1) {
+        if (!keys2.includes(key)) {
+            return false
+        }
+        if (!isDeepEqual(obj1[key], obj2[key], visited)) {
+            return false
+        }
+    }
+
+    return true
+}

package/src/utils/type-utils.ts

@@ -0,0 +1,16 @@
+// from a comment on http://dbj.org/dbj/?p=286
+// fails on only one very rare and deliberate custom object:
+// let bomb = { toString : undefined, valueOf: function(o) { return "function BOMBA!"; }};
+export const isFunction = function (f: any): f is (...args: any[]) => any {
+    // eslint-disable-next-line posthog-js/no-direct-function-check
+    return typeof f === 'function'
+}
+
+export const isUndefined = function (x: unknown): x is undefined {
+    return x === void 0
+}
+
+export const isNull = function (x: unknown): x is null {
+    // eslint-disable-next-line posthog-js/no-direct-null-check
+    return x === null
+}