feat(react-native): enable captureAppLifecycleEvents by default and add @default JSDoc tags

.changeset/tiny-birds-dream.md

@@ -0,0 +1,5 @@
+---
+'@posthog/core': patch
+---
+
+Add `@default` JSDoc tags to `PostHogCoreOptions` configuration properties for better IDE documentation and discoverability.

.changeset/warm-foxes-wave.md

@@ -0,0 +1,19 @@
+---
+'posthog-react-native': minor
+---
+
+`captureAppLifecycleEvents` is now enabled by default. If you want to disable it, you can set `captureAppLifecycleEvents: false` in the PostHog options:
+
+```js
+const posthog = new PostHog('<ph_project_api_key>', {
+  captureAppLifecycleEvents: false,
+})
+```
+
+Or when using the PostHogProvider:
+
+```jsx
+<PostHogProvider apiKey="<ph_project_api_key>" options={{ captureAppLifecycleEvents: false }}>
+  <MyApp />
+</PostHogProvider>
+```

packages/core/src/types.ts

@@ -1,34 +1,71 @@
 export type PostHogCoreOptions = {
-  /** PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' */
+  /**
+   * PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
+   *
+   * @default 'https://us.i.posthog.com'
+   */
   host?: string
-  /** The number of events to queue before sending to PostHog (flushing) */
+  /**
+   * The number of events to queue before sending to PostHog (flushing)
+   *
+   * @default 20
+   */
   flushAt?: number
-  /** The interval in milliseconds between periodic flushes */
+  /**
+   * The interval in milliseconds between periodic flushes
+   *
+   * @default 10000
+   */
   flushInterval?: number
-  /** The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`) */
+  /**
+   * The maximum number of queued messages to be flushed as part of a single batch (must be higher than `flushAt`)
+   *
+   * @default 100
+   */
   maxBatchSize?: number
-  /** The maximum number of cached messages either in memory or on the local storage.
-   * Defaults to 1000, (must be higher than `flushAt`)
+  /**
+   * The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`)
+   *
+   * @default 1000
    */
   maxQueueSize?: number
-  /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
+  /**
+   * If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything)
+   *
+   * @default false
+   */
   disabled?: boolean
-  /** If set to false the SDK will not track until the `optIn` function is called. */
+  /**
+   * If set to false the SDK will not track until the `optIn` function is called.
+   *
+   * @default true
+   */
   defaultOptIn?: boolean
-  /** Whether to track that `getFeatureFlag` was called (used by Experiments) */
+  /**
+   * Whether to track that `getFeatureFlag` was called (used by Experiments)
+   *
+   * @default true
+   */
   sendFeatureFlagEvent?: boolean
-  /** Whether to load feature flags when initialized or not */
+  /**
+   * Whether to load feature flags when initialized or not
+   *
+   * @default true
+   */
   preloadFeatureFlags?: boolean
   /**
    * Whether to load remote config when initialized or not
    * Experimental support
-   * Default: false - Remote config is loaded by default
+   *
+   * @default false
    */
   disableRemoteConfig?: boolean
   /**
    * Whether to load surveys when initialized or not
    * Experimental support
-   * Default: false - Surveys are loaded by default, but requires the `PostHogSurveyProvider` to be used
+   * Requires the `PostHogSurveyProvider` to be used
+   *
+   * @default false
    */
   disableSurveys?: boolean
   /** Option to bootstrap the library with given distinctId and feature flags */
@@ -38,22 +75,59 @@ export type PostHogCoreOptions = {
     featureFlags?: Record<string, FeatureFlagValue>
     featureFlagPayloads?: Record<string, JsonType>
   }
-  /** How many times we will retry HTTP requests. Defaults to 3. */
+  /**
+   * How many times we will retry HTTP requests
+   *
+   * @default 3
+   */
   fetchRetryCount?: number
-  /** The delay between HTTP request retries, Defaults to 3 seconds. */
+  /**
+   * The delay between HTTP request retries in milliseconds
+   *
+   * @default 3000
+   */
   fetchRetryDelay?: number
-  /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */
+  /**
+   * Timeout in milliseconds for any calls
+   *
+   * @default 10000
+   */
   requestTimeout?: number
-  /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
+  /**
+   * Timeout in milliseconds for feature flag calls
+   *
+   * @default 10000 for stateful clients, 3000 for stateless
+   */
   featureFlagsRequestTimeoutMs?: number
-  /** Timeout in milliseconds for remote config calls. Defaults to 3 seconds. */
+  /**
+   * Timeout in milliseconds for remote config calls
+   *
+   * @default 3000
+   */
   remoteConfigRequestTimeoutMs?: number
-  /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
+  /**
+   * For Session Analysis how long before we expire a session in seconds
+   *
+   * @default 1800
+   */
   sessionExpirationTimeSeconds?: number
-  /** Whether to disable GZIP compression */
+  /**
+   * Whether to disable GZIP compression
+   *
+   * @default false
+   */
   disableCompression?: boolean
+  /**
+   * Whether to disable GeoIP lookups
+   *
+   * @default false
+   */
   disableGeoip?: boolean
-  /** Special flag to indicate ingested data is for a historical migration. */
+  /**
+   * Special flag to indicate ingested data is for a historical migration
+   *
+   * @default false
+   */
   historicalMigration?: boolean
   /**
    * Evaluation contexts for feature flags.

packages/react-native/src/PostHogProvider.tsx

@@ -21,9 +21,23 @@ export interface PostHogProviderProps {
   apiKey?: string
   /** An existing PostHog client instance */
   client?: PostHog
-  /** Autocapture configuration - can be a boolean or detailed options */
+  /**
+   * Autocapture configuration - can be a boolean or detailed options.
+   *
+   * When not set, the default behavior is:
+   * - `captureScreens`: true
+   * - `captureTouches`: false
+   * - `captureAppLifecycleEvents`: true
+   *
+   * Set to `true` to enable all autocapture features (including touches).
+   * Set to `false` to disable all autocapture features.
+   */
   autocapture?: boolean | PostHogAutocaptureOptions
-  /** Enable debug mode for additional logging */
+  /**
+   * Enable debug mode for additional logging
+   *
+   * @default false
+   */
   debug?: boolean
   /** Custom styles for the provider wrapper View */
   style?: StyleProp<ViewStyle>
@@ -132,9 +146,7 @@ export const PostHogProvider = ({
     const parsedOptions = {
       ...options,
       captureAppLifecycleEvents:
-        options?.captureAppLifecycleEvents !== undefined
-          ? options.captureAppLifecycleEvents
-          : !captureNone && captureAll,
+        options?.captureAppLifecycleEvents !== undefined ? options.captureAppLifecycleEvents : !captureNone,
     }
 
     return new PostHog(apiKey ?? '', parsedOptions)

packages/react-native/src/posthog-rn.ts

@@ -33,30 +33,37 @@ import { ErrorTracking, ErrorTrackingOptions } from './error-tracking'
 export { PostHogPersistedProperty }
 
 export interface PostHogOptions extends PostHogCoreOptions {
-  /** Allows you to provide the storage type. By default 'file'.
+  /**
+   * Allows you to provide the storage type.
    * 'file' will try to load the best available storage, the provided 'customStorage', 'customAsyncStorage' or in-memory storage.
+   *
+   * @default 'file'
    */
   persistence?: 'memory' | 'file'
   /** Allows you to provide your own implementation of the common information about your App or a function to modify the default App properties generated */
   customAppProperties?:
     | PostHogCustomAppProperties
     | ((properties: PostHogCustomAppProperties) => PostHogCustomAppProperties)
-  /** Allows you to provide a custom asynchronous storage such as async-storage, expo-file-system or a synchronous storage such as mmkv.
+  /**
+   * Allows you to provide a custom asynchronous storage such as async-storage, expo-file-system or a synchronous storage such as mmkv.
    * If not provided, PostHog will attempt to use the best available storage via optional peer dependencies (async-storage, expo-file-system).
    * If `persistence` is set to 'memory', this option will be ignored.
    */
   customStorage?: PostHogCustomStorage
 
-  /** Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active and Application Backgrounded.
-   * By default is false.
+  /**
+   * Captures app lifecycle events such as Application Installed, Application Updated, Application Opened, Application Became Active and Application Backgrounded.
    * Application Installed and Application Updated events are not supported with persistence set to 'memory'.
+   *
+   * @default true
    */
   captureAppLifecycleEvents?: boolean
 
   /**
    * Enable Recording of Session Replays for Android and iOS
    * Requires Record user sessions to be enabled in the PostHog Project Settings
-   * Defaults to false
+   *
+   * @default false
    */
   enableSessionReplay?: boolean
 
@@ -69,7 +76,8 @@ export interface PostHogOptions extends PostHogCoreOptions {
    * If enabled, the session id ($session_id) will be persisted across app restarts.
    * This is an option for back compatibility, so your current data isn't skewed with the new version of the SDK.
    * If this is false, the session id will be always reset on app restart.
-   * Defaults to false
+   *
+   * @default false
    */
   enablePersistSessionIdAcrossRestart?: boolean
 
@@ -266,7 +274,8 @@ export class PostHog extends PostHogCore {
         }
       }
 
-      if (options?.captureAppLifecycleEvents) {
+      // captureAppLifecycleEvents defaults to true; only skip if explicitly set to false
+      if (options?.captureAppLifecycleEvents !== false) {
         void this.captureAppLifecycleEvents()
       }
 

packages/react-native/src/types.ts

@@ -13,12 +13,41 @@ export type PostHogNavigationRef = {
 }
 
 export type PostHogAutocaptureOptions = {
-  // Touches
+  /**
+   * Enable autocapture of touch events
+   *
+   * @default false
+   */
   captureTouches?: boolean
+  /**
+   * Custom prop name used to label elements for autocapture
+   *
+   * @default 'ph-label'
+   */
   customLabelProp?: string
+  /**
+   * Prop name used to prevent autocapture on an element and its children
+   *
+   * @default 'ph-no-capture'
+   */
   noCaptureProp?: string
+  /**
+   * Maximum number of elements to capture in the component tree hierarchy
+   *
+   * @default 20
+   */
   maxElementsCaptured?: number
+  /**
+   * List of element labels to ignore during autocapture
+   *
+   * @default []
+   */
   ignoreLabels?: string[]
+  /**
+   * List of prop names to capture from elements
+   *
+   * @default ['style', 'testID', 'accessibilityLabel', 'ph-label', 'children']
+   */
   propsToCapture?: string[]
 
   /**
@@ -95,41 +124,47 @@ export interface PostHogCustomAppProperties {
 export type PostHogSessionReplayConfig = {
   /**
    * Enable masking of all text and text input fields
-   * Default: true
+   *
+   * @default true
    */
   maskAllTextInputs?: boolean
   /**
    * Enable masking of all images to a placeholder
-   * Default: true
+   *
+   * @default true
    */
   maskAllImages?: boolean
   /**
    * Enable masking of all sandboxed system views
    * These may include UIImagePickerController, PHPickerViewController and CNContactPickerViewController
    * iOS only
    * Experimental support
-   * Default: true
+   *
+   * @default true
    */
   maskAllSandboxedViews?: boolean
   /**
    * Enable capturing of logs as console events
-   * Default: true
+   *
+   * @default true
    */
   captureLog?: boolean
   /**
    * Deboucer delay used to reduce the number of snapshots captured and reduce performance impact
    * This is used for capturing the view as a screenshot
    * The lower the number more snapshots will be captured but higher the performance impact
-   * Defaults to 1s on iOS
+   *
+   * @default 1000
    * @deprecated please use throttleDelayMs instead
    */
   iOSdebouncerDelayMs?: number
   /**
    * Deboucer delay used to reduce the number of snapshots captured and reduce performance impact
    * This is used for capturing the view as a screenshot
    * The lower the number more snapshots will be captured but higher the performance impact
-   * Defaults to 1000ms (1s)
    * Ps: it was 500ms (0.5s) by default until version 3.3.7
+   *
+   * @default 1000
    * @deprecated please use throttleDelayMs instead
    */
   androidDebouncerDelayMs?: number
@@ -141,13 +176,14 @@ export type PostHogSessionReplayConfig = {
    * This value has precedence over iOSdebouncerDelayMs and androidDebouncerDelayMs
    * If this is not set, we will take the max number between iOSdebouncerDelayMs and androidDebouncerDelayMs for back compatibility
    *
-   * Defaults to 1000ms = 1s
+   * @default 1000
    */
   throttleDelayMs?: number
   /**
    * Enable capturing network telemetry
    * iOS only
-   * Default: true
+   *
+   * @default true
    */
   captureNetworkTelemetry?: boolean
   /**