posthog-js 1.288.1 → 1.290.0

package/dist/src/posthog-core.d.ts

@@ -82,6 +82,7 @@ export declare class PostHog {
     _triggered_notifs: any;
     compression?: Compression;
     __request_queue: QueuedRequestWithOptions[];
+    _pendingRemoteConfig?: RemoteConfig;
     analyticsDefaultEndpoint: string;
     version: string;
     _initialPersonProfilesConfig: 'always' | 'never' | 'identified_only' | null;
@@ -132,6 +133,8 @@ export declare class PostHog {
      */
     init(token: string, config?: OnlyValidKeys<Partial<PostHogConfig>, Partial<PostHogConfig>>, name?: string): PostHog;
     _init(token: string, config?: Partial<PostHogConfig>, name?: string): PostHog;
+    private _initExtensions;
+    private _processInitTaskQueue;
     _onRemoteConfig(config: RemoteConfig): void;
     _loaded(): void;
     _start_queue_if_opted_in(): void;

package/dist/src/types.d.ts

@@ -566,6 +566,20 @@ export interface PostHogConfig {
      * @default 'unset'
      */
     defaults: ConfigDefaults;
+    /**
+     * EXPERIMENTAL: Defers initialization of non-critical extensions (autocapture, session recording, etc.)
+     * to the next event loop tick using setTimeout. This reduces main thread blocking during SDK
+     * initialization for better page load performance, while keeping critical functionality
+     * (persistence, sessions, capture) available immediately.
+     *
+     * When enabled:
+     * - Persistence, sessions, and basic capture work immediately
+     * - Extensions (autocapture, recording, heatmaps, etc.) start after yielding back to the browser
+     *
+     * @default false (will be true for defaults >= '2025-11-06' in the future)
+     * @experimental
+     */
+    __preview_deferred_init_extensions: boolean;
     /**
      * Determines the session recording options.
      *

package/dist/surveys-preview.d.ts

@@ -1363,6 +1363,20 @@ interface PostHogConfig {
      * @default 'unset'
      */
     defaults: ConfigDefaults;
+    /**
+     * EXPERIMENTAL: Defers initialization of non-critical extensions (autocapture, session recording, etc.)
+     * to the next event loop tick using setTimeout. This reduces main thread blocking during SDK
+     * initialization for better page load performance, while keeping critical functionality
+     * (persistence, sessions, capture) available immediately.
+     *
+     * When enabled:
+     * - Persistence, sessions, and basic capture work immediately
+     * - Extensions (autocapture, recording, heatmaps, etc.) start after yielding back to the browser
+     *
+     * @default false (will be true for defaults >= '2025-11-06' in the future)
+     * @experimental
+     */
+    __preview_deferred_init_extensions: boolean;
     /**
      * Determines the session recording options.
      *
@@ -3231,6 +3245,7 @@ declare class PostHog {
     _triggered_notifs: any;
     compression?: Compression;
     __request_queue: QueuedRequestWithOptions[];
+    _pendingRemoteConfig?: RemoteConfig;
     analyticsDefaultEndpoint: string;
     version: string;
     _initialPersonProfilesConfig: 'always' | 'never' | 'identified_only' | null;
@@ -3281,6 +3296,8 @@ declare class PostHog {
      */
     init(token: string, config?: OnlyValidKeys<Partial<PostHogConfig>, Partial<PostHogConfig>>, name?: string): PostHog;
     _init(token: string, config?: Partial<PostHogConfig>, name?: string): PostHog;
+    private _initExtensions;
+    private _processInitTaskQueue;
     _onRemoteConfig(config: RemoteConfig): void;
     _loaded(): void;
     _start_queue_if_opted_in(): void;

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "posthog-js",
-    "version": "1.288.1",
+    "version": "1.290.0",
     "description": "Posthog-js allows you to automatically capture usage and send events to PostHog.",
     "repository": "https://github.com/PostHog/posthog-js",
     "author": "hey@posthog.com",

package/lib/src/entrypoints/array.full.es5.js

@@ -7,6 +7,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // and it doesn't include "web-vitals" which doesn't support IE11
 require("core-js/features/object/entries");
 require("core-js/features/object/from-entries");
+if (typeof performance === 'undefined' || typeof performance.now !== 'function') {
+    var perf = typeof performance !== 'undefined' ? performance : {};
+    perf.now = perf.now || (function () { return Date.now(); });
+    if (typeof performance === 'undefined') {
+        // eslint-disable-next-line no-restricted-globals
+        ;
+        window.performance = perf;
+    }
+}
 require("./surveys");
 require("./exception-autocapture");
 require("./tracing-headers");

package/lib/src/entrypoints/array.full.es5.js.map

@@ -1 +1 @@
-{"version":3,"file":"array.full.es5.js","sourceRoot":"","sources":["../../../src/entrypoints/array.full.es5.ts"],"names":[],"mappings":";AAAA,mDAAmD;AACnD,4DAA4D;AAC5D,4BAA4B;;AAE5B,0DAA0D;AAC1D,iEAAiE;AAEjE,2CAAwC;AACxC,gDAA6C;AAE7C,qBAAkB;AAClB,mCAAgC;AAChC,6BAA0B;AAC1B,+BAA4B","sourcesContent":["// a straight copy of the array.full.ts entrypoint,\n// but will have different config when passed through rollup\n// to allow es5/IE11 support\n\n// it doesn't include recorder which doesn't support IE11,\n// and it doesn't include \"web-vitals\" which doesn't support IE11\n\nimport 'core-js/features/object/entries'\nimport 'core-js/features/object/from-entries'\n\nimport './surveys'\nimport './exception-autocapture'\nimport './tracing-headers'\nimport './array.no-external'\n"]}
+{"version":3,"file":"array.full.es5.js","sourceRoot":"","sources":["../../../src/entrypoints/array.full.es5.ts"],"names":[],"mappings":";AAAA,mDAAmD;AACnD,4DAA4D;AAC5D,4BAA4B;;AAE5B,0DAA0D;AAC1D,iEAAiE;AAEjE,2CAAwC;AACxC,gDAA6C;AAE7C,IAAI,OAAO,WAAW,KAAK,WAAW,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;IAC9E,IAAM,IAAI,GAAG,OAAO,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,EAAU,CAAA;IAC3E,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,cAAM,OAAA,IAAI,CAAC,GAAG,EAAE,EAAV,CAAU,CAAC,CAAA;IACzC,IAAI,OAAO,WAAW,KAAK,WAAW,EAAE,CAAC;QACrC,iDAAiD;QACjD,CAAC;QAAC,MAAc,CAAC,WAAW,GAAG,IAAI,CAAA;IACvC,CAAC;AACL,CAAC;AAED,qBAAkB;AAClB,mCAAgC;AAChC,6BAA0B;AAC1B,+BAA4B","sourcesContent":["// a straight copy of the array.full.ts entrypoint,\n// but will have different config when passed through rollup\n// to allow es5/IE11 support\n\n// it doesn't include recorder which doesn't support IE11,\n// and it doesn't include \"web-vitals\" which doesn't support IE11\n\nimport 'core-js/features/object/entries'\nimport 'core-js/features/object/from-entries'\n\nif (typeof performance === 'undefined' || typeof performance.now !== 'function') {\n    const perf = typeof performance !== 'undefined' ? performance : ({} as any)\n    perf.now = perf.now || (() => Date.now())\n    if (typeof performance === 'undefined') {\n        // eslint-disable-next-line no-restricted-globals\n        ;(window as any).performance = perf\n    }\n}\n\nimport './surveys'\nimport './exception-autocapture'\nimport './tracing-headers'\nimport './array.no-external'\n"]}

package/lib/src/posthog-core.d.ts

@@ -82,6 +82,7 @@ export declare class PostHog {
     _triggered_notifs: any;
     compression?: Compression;
     __request_queue: QueuedRequestWithOptions[];
+    _pendingRemoteConfig?: RemoteConfig;
     analyticsDefaultEndpoint: string;
     version: string;
     _initialPersonProfilesConfig: 'always' | 'never' | 'identified_only' | null;
@@ -132,6 +133,8 @@ export declare class PostHog {
      */
     init(token: string, config?: OnlyValidKeys<Partial<PostHogConfig>, Partial<PostHogConfig>>, name?: string): PostHog;
     _init(token: string, config?: Partial<PostHogConfig>, name?: string): PostHog;
+    private _initExtensions;
+    private _processInitTaskQueue;
     _onRemoteConfig(config: RemoteConfig): void;
     _loaded(): void;
     _start_queue_if_opted_in(): void;

package/lib/src/posthog-core.js

@@ -133,6 +133,7 @@ var defaultConfig = function (defaults) {
         capture_pageview: defaults === '2025-05-24' ? 'history_change' : true,
         capture_pageleave: 'if_capture_pageview', // We'll only capture pageleave events if capture_pageview is also true
         defaults: defaults !== null && defaults !== void 0 ? defaults : 'unset',
+        __preview_deferred_init_extensions: false, // Opt-in only for now
         debug: (globals_1.location && (0, core_1.isString)(globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.search) && globals_1.location.search.indexOf('__posthog_debug=true') !== -1) || false,
         cookie_expiration: 365,
         upgrade: false,
@@ -388,7 +389,7 @@ var PostHog = /** @class */ (function () {
     //
     PostHog.prototype._init = function (token, config, name) {
         var _this = this;
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e;
         if (config === void 0) { config = {}; }
         if ((0, core_1.isUndefined)(token) || (0, core_1.isEmptyString)(token)) {
             logger_1.logger.critical('PostHog was initialized without a token. This likely indicates a misconfiguration. Please check the first argument passed to posthog.init()');
@@ -435,28 +436,21 @@ var PostHog = /** @class */ (function () {
             this.sessionManager = new sessionid_1.SessionIdManager(this);
             this.sessionPropsManager = new session_props_1.SessionPropsManager(this, this.sessionManager, this.persistence);
         }
-        new tracing_headers_1.TracingHeaders(this).startIfEnabledOrStop();
-        this.siteApps = new site_apps_1.SiteApps(this);
-        (_a = this.siteApps) === null || _a === void 0 ? void 0 : _a.init();
-        if (!startInCookielessMode) {
-            this.sessionRecording = new session_recording_1.SessionRecording(this);
-            this.sessionRecording.startIfEnabledOrStop();
+        // Conditionally defer extension initialization based on config
+        if (this.config.__preview_deferred_init_extensions) {
+            // EXPERIMENTAL: Defer non-critical extension initialization to next tick
+            // This reduces main thread blocking during init
+            // while keeping critical path (persistence, sessions, capture) synchronous
+            logger_1.logger.info('Deferring extension initialization to improve startup performance');
+            setTimeout(function () {
+                _this._initExtensions(startInCookielessMode);
+            }, 0);
+        }
+        else {
+            // Legacy synchronous initialization (default for now)
+            logger_1.logger.info('Initializing extensions synchronously');
+            this._initExtensions(startInCookielessMode);
         }
-        if (!this.config.disable_scroll_properties) {
-            this.scrollManager.startMeasuringScrollPosition();
-        }
-        this.autocapture = new autocapture_1.Autocapture(this);
-        this.autocapture.startIfEnabled();
-        this.surveys.loadIfEnabled();
-        this.heatmaps = new heatmaps_1.Heatmaps(this);
-        this.heatmaps.startIfEnabled();
-        this.webVitalsAutocapture = new web_vitals_1.WebVitalsAutocapture(this);
-        this.exceptionObserver = new exception_autocapture_1.ExceptionObserver(this);
-        this.exceptionObserver.startIfEnabled();
-        this.deadClicksAutocapture = new dead_clicks_autocapture_1.DeadClicksAutocapture(this, dead_clicks_autocapture_1.isDeadClicksEnabledForAutocapture);
-        this.deadClicksAutocapture.startIfEnabled();
-        this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
-        this.historyAutocapture.startIfEnabled();
         // if any instance on the page has debug = true, we set the
         // global debug to be true
         config_1.default.DEBUG = config_1.default.DEBUG || this.config.debug;
@@ -471,23 +465,23 @@ var PostHog = /** @class */ (function () {
         }
         // isUndefined doesn't provide typehint here so wouldn't reduce bundle as we'd need to assign
         // eslint-disable-next-line posthog-js/no-direct-undefined-check
-        if (((_b = config.bootstrap) === null || _b === void 0 ? void 0 : _b.distinctID) !== undefined) {
+        if (((_a = config.bootstrap) === null || _a === void 0 ? void 0 : _a.distinctID) !== undefined) {
             var uuid = this.config.get_device_id((0, uuidv7_1.uuidv7)());
-            var deviceID = ((_c = config.bootstrap) === null || _c === void 0 ? void 0 : _c.isIdentifiedID) ? uuid : config.bootstrap.distinctID;
-            this.persistence.set_property(constants_1.USER_STATE, ((_d = config.bootstrap) === null || _d === void 0 ? void 0 : _d.isIdentifiedID) ? 'identified' : 'anonymous');
+            var deviceID = ((_b = config.bootstrap) === null || _b === void 0 ? void 0 : _b.isIdentifiedID) ? uuid : config.bootstrap.distinctID;
+            this.persistence.set_property(constants_1.USER_STATE, ((_c = config.bootstrap) === null || _c === void 0 ? void 0 : _c.isIdentifiedID) ? 'identified' : 'anonymous');
             this.register({
                 distinct_id: config.bootstrap.distinctID,
                 $device_id: deviceID,
             });
         }
         if (this._hasBootstrappedFeatureFlags()) {
-            var activeFlags_1 = Object.keys(((_e = config.bootstrap) === null || _e === void 0 ? void 0 : _e.featureFlags) || {})
+            var activeFlags_1 = Object.keys(((_d = config.bootstrap) === null || _d === void 0 ? void 0 : _d.featureFlags) || {})
                 .filter(function (flag) { var _a, _b; return !!((_b = (_a = config.bootstrap) === null || _a === void 0 ? void 0 : _a.featureFlags) === null || _b === void 0 ? void 0 : _b[flag]); })
                 .reduce(function (res, key) {
                 var _a, _b;
                 return ((res[key] = ((_b = (_a = config.bootstrap) === null || _a === void 0 ? void 0 : _a.featureFlags) === null || _b === void 0 ? void 0 : _b[key]) || false), res);
             }, {});
-            var featureFlagPayloads = Object.keys(((_f = config.bootstrap) === null || _f === void 0 ? void 0 : _f.featureFlagPayloads) || {})
+            var featureFlagPayloads = Object.keys(((_e = config.bootstrap) === null || _e === void 0 ? void 0 : _e.featureFlagPayloads) || {})
                 .filter(function (key) { return activeFlags_1[key]; })
                 .reduce(function (res, key) {
                 var _a, _b, _c, _d;
@@ -540,6 +534,110 @@ var PostHog = /** @class */ (function () {
         }
         return this;
     };
+    PostHog.prototype._initExtensions = function (startInCookielessMode) {
+        var _this = this;
+        // we don't support IE11 anymore, so performance.now is safe
+        // eslint-disable-next-line compat/compat
+        var initStartTime = performance.now();
+        this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
+        this.historyAutocapture.startIfEnabled();
+        // Build queue of extension initialization tasks
+        var initTasks = [];
+        initTasks.push(function () {
+            new tracing_headers_1.TracingHeaders(_this).startIfEnabledOrStop();
+        });
+        initTasks.push(function () {
+            var _a;
+            _this.siteApps = new site_apps_1.SiteApps(_this);
+            (_a = _this.siteApps) === null || _a === void 0 ? void 0 : _a.init();
+        });
+        if (!startInCookielessMode) {
+            initTasks.push(function () {
+                _this.sessionRecording = new session_recording_1.SessionRecording(_this);
+                _this.sessionRecording.startIfEnabledOrStop();
+            });
+        }
+        if (!this.config.disable_scroll_properties) {
+            initTasks.push(function () {
+                _this.scrollManager.startMeasuringScrollPosition();
+            });
+        }
+        initTasks.push(function () {
+            _this.autocapture = new autocapture_1.Autocapture(_this);
+            _this.autocapture.startIfEnabled();
+        });
+        initTasks.push(function () {
+            _this.surveys.loadIfEnabled();
+        });
+        initTasks.push(function () {
+            _this.heatmaps = new heatmaps_1.Heatmaps(_this);
+            _this.heatmaps.startIfEnabled();
+        });
+        initTasks.push(function () {
+            _this.webVitalsAutocapture = new web_vitals_1.WebVitalsAutocapture(_this);
+        });
+        initTasks.push(function () {
+            _this.exceptionObserver = new exception_autocapture_1.ExceptionObserver(_this);
+            _this.exceptionObserver.startIfEnabled();
+        });
+        initTasks.push(function () {
+            _this.deadClicksAutocapture = new dead_clicks_autocapture_1.DeadClicksAutocapture(_this, dead_clicks_autocapture_1.isDeadClicksEnabledForAutocapture);
+            _this.deadClicksAutocapture.startIfEnabled();
+        });
+        // Replay any pending remote config that arrived before extensions were ready
+        initTasks.push(function () {
+            if (_this._pendingRemoteConfig) {
+                var config = _this._pendingRemoteConfig;
+                _this._pendingRemoteConfig = undefined; // Clear before replaying to avoid re-storing
+                _this._onRemoteConfig(config);
+            }
+        });
+        // Process tasks with time-slicing to avoid blocking
+        this._processInitTaskQueue(initTasks, initStartTime);
+    };
+    PostHog.prototype._processInitTaskQueue = function (queue, initStartTime) {
+        var _this = this;
+        var TIME_BUDGET_MS = 30; // Respect frame budget (~60fps = 16ms, but we're already deferred)
+        while (queue.length > 0) {
+            // Only time-slice if deferred init is enabled, otherwise run synchronously
+            if (this.config.__preview_deferred_init_extensions) {
+                // we don't support IE11 anymore, so performance.now is safe
+                // eslint-disable-next-line compat/compat
+                var elapsed = performance.now() - initStartTime;
+                // Check if we've exceeded our time budget
+                if (elapsed >= TIME_BUDGET_MS && queue.length > 0) {
+                    // Yield to browser, then continue processing
+                    setTimeout(function () {
+                        _this._processInitTaskQueue(queue, initStartTime);
+                    }, 0);
+                    return;
+                }
+            }
+            // Process next task
+            var task = queue.shift();
+            if (task) {
+                try {
+                    task();
+                }
+                catch (error) {
+                    logger_1.logger.error('Error initializing extension:', error);
+                }
+            }
+        }
+        // All tasks complete - record timing for both sync and deferred modes
+        // we don't support IE11 anymore, so performance.now is safe
+        // eslint-disable-next-line compat/compat
+        var taskInitTiming = Math.round(performance.now() - initStartTime);
+        this.register_for_session({
+            $sdk_debug_extensions_init_method: this.config.__preview_deferred_init_extensions
+                ? 'deferred'
+                : 'synchronous',
+            $sdk_debug_extensions_init_time_ms: taskInitTiming,
+        });
+        if (this.config.__preview_deferred_init_extensions) {
+            logger_1.logger.info("PostHog extensions initialized (".concat(taskInitTiming, "ms)"));
+        }
+    };
     PostHog.prototype._onRemoteConfig = function (config) {
         var _this = this;
         var _a, _b, _c, _d, _e, _f, _g, _h;
@@ -550,6 +648,10 @@ var PostHog = /** @class */ (function () {
             }, 500);
             return;
         }
+        // Store config in case extensions aren't initialized yet (only needed for deferred init)
+        if (this.config.__preview_deferred_init_extensions) {
+            this._pendingRemoteConfig = config;
+        }
         this.compression = undefined;
         if (config.supportedCompression && !this.config.disable_compression) {
             this.compression = (0, core_1.includes)(config['supportedCompression'], types_1.Compression.GZipJS)