:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(frontend): load the app modules while the user's data loads (#127406)
Paul D'Ambra17861e57630c
diff --git a/frontend/src/index.test.tsx b/frontend/src/index.test.tsxindex 29dfe8d1141e..8688c87b933b 100644--- a/frontend/src/index.test.tsx+++ b/frontend/src/index.test.tsx@@ -59,6 +59,7 @@ describe('app entry boot', () => {await act(async () => window.__posthogAppRoot?.unmount())delete window.__posthogAppRootdelete window.ESBUILD_CSS_READY+ delete window.POSTHOG_APP_CONTEXT_REQUESTdocument.body.innerHTML = ''jest.clearAllTimers()jest.useRealTimers()@@ -98,6 +99,21 @@ describe('app entry boot', () => {})+ it('loads modules while the user data is pending and boots once it arrives', async () => {+ const userData = deferred<{ app_context: object; feature_flags: null }>()+ window.POSTHOG_APP_CONTEXT_REQUEST = userData.promise+ await loadEntry()+ await act(async () => stylesheet.resolve(true))++ expect(modulesLoaded).toEqual(['App', 'bootApp'])+ expect(bootApp).not.toHaveBeenCalled()++ await act(async () => userData.resolve({ app_context: {}, feature_flags: null }))++ expect(document.querySelector('[data-attr="boot-test-app"]')).toBeInTheDocument()+ expect(bootApp).toHaveBeenCalledTimes(1)+ })+it.each(['loaded', 'absent'] as const)('boots when the stylesheet is %s', async (stylesheetState) => {if (stylesheetState === 'absent') {delete window.ESBUILD_CSS_READYdiff --git a/frontend/src/index.tsx b/frontend/src/index.tsxindex bf2c22b4f4f3..62d40810b18b 100644--- a/frontend/src/index.tsx+++ b/frontend/src/index.tsx@@ -6,7 +6,7 @@ import { Suspense, lazy } from 'react'import { createRoot, type Root } from 'react-dom/client'import { markBootPhase } from 'lib/utils/bootTiming'-import { applyDeferredAppContext } from 'lib/utils/deferredAppContext'+import { applyDeferredAppContext, watchEarlyUserContextReads } from 'lib/utils/deferredAppContext'import { retryBootImport } from 'lib/utils/retryImport'import { RootErrorBoundary } from './RootErrorBoundary'@@ -16,22 +16,23 @@ markBootPhase('entry', {deferred_app_context: !!window.POSTHOG_APP_CONTEXT_REQUEST,deferred_app_context_variant: window.POSTHOG_APP_CONTEXT?.deferred_app_context_variant,})+watchEarlyUserContextReads()type AppModules = [typeof import('scenes/App'), typeof import('scenes/bootApp')]let appModulesPromise: Promise<AppModules> | undefinedfunction loadAppModules(): Promise<AppModules> {- // Some app modules read the app context when they load. The modulepreload links still fetch their code meanwhile.- return (appModulesPromise ??= applyDeferredAppContext()- .then(() =>- Promise.all([retryBootImport(() => import('scenes/App')), retryBootImport(() => import('scenes/bootApp'))])- )- .then((modules) => {- // Marked here, not in the lazy() factory: React calls the factory only after the CSS gate in boot().- markBootPhase('app_modules_loaded')- return modules- }))+ // The user's data can arrive after these modules load, so they must not read it at load time.+ // scenes/bootModules.test.ts checks this.+ return (appModulesPromise ??= Promise.all([+ retryBootImport(() => import('scenes/App')),+ retryBootImport(() => import('scenes/bootApp')),+ ]).then((modules) => {+ // Marked here, not in the lazy() factory: React calls the factory only after the CSS gate in boot().+ markBootPhase('app_modules_loaded')+ return modules+ }))}// Lazy-load App so the entry chunk stays minimal: the entire transitive dependency@@ -42,7 +43,7 @@ function loadAppModules(): Promise<AppModules> {// React Fast Refresh boundary.// boot() also starts the module imports while CSS loads; runtime initialization stays behind the render gate.const App = lazy(() =>- loadAppModules().then(([appModule, bootModule]) => {+ Promise.all([loadAppModules(), applyDeferredAppContext()]).then(([[appModule, bootModule]]) => {bootModule.bootApp()markBootPhase('app_booted')return { default: appModule.App }diff --git a/frontend/src/lib/utils/bootTiming.ts b/frontend/src/lib/utils/bootTiming.tsindex 3de05bbc4001..c78fe8699df1 100644--- a/frontend/src/lib/utils/bootTiming.ts+++ b/frontend/src/lib/utils/bootTiming.ts@@ -18,6 +18,7 @@ export interface BootContext {logged_in?: booleandeferred_app_context?: booleandeferred_app_context_variant?: string+ early_user_context_reads?: string[]}const phaseTimes: Partial<Record<BootPhase, number>> = {}diff --git a/frontend/src/lib/utils/deferredAppContext.test.ts b/frontend/src/lib/utils/deferredAppContext.test.tsindex 01833069d4b6..016e4d8a5ccd 100644--- a/frontend/src/lib/utils/deferredAppContext.test.ts+++ b/frontend/src/lib/utils/deferredAppContext.test.ts@@ -1,6 +1,11 @@import { AppContext, UserType } from '~/types'-import { applyDeferredAppContext, inlineAppContextUrl } from './deferredAppContext'+import {+ applyDeferredAppContext,+ earlyUserContextReads,+ inlineAppContextUrl,+ watchEarlyUserContextReads,+} from './deferredAppContext'describe('deferredAppContext', () => {afterEach(() => {@@ -14,20 +19,36 @@ describe('deferredAppContext', () => {app_context: { current_user: { distinct_id: 'user-1' } as UserType },feature_flags: { 'some-flag': true },})+ const contextKeptBeforeTheData = window.POSTHOG_APP_CONTEXTawait applyDeferredAppContext()- expect(window.POSTHOG_APP_CONTEXT).toEqual({- anonymous: false,- deferred: true,- current_user: { distinct_id: 'user-1' },- })+ const merged = { anonymous: false, deferred: true, current_user: { distinct_id: 'user-1' } }+ expect(window.POSTHOG_APP_CONTEXT).toEqual(merged)+ expect(contextKeptBeforeTheData).toEqual(merged)expect(window.POSTHOG_USER_IDENTITY_WITH_FLAGS).toEqual({distinctID: 'page-distinct-id',featureFlags: { 'some-flag': true },})})+ it('records the user data read before the data arrives', async () => {+ let resolveRequest!: (value: { app_context: Partial<AppContext>; feature_flags: null }) => void+ window.POSTHOG_APP_CONTEXT_REQUEST = new Promise((resolve) => {+ resolveRequest = resolve+ })+ window.POSTHOG_APP_CONTEXT = { anonymous: false, deferred: true } as unknown as AppContext+ watchEarlyUserContextReads()++ void window.POSTHOG_APP_CONTEXT.current_team+ void window.POSTHOG_APP_CONTEXT.anonymous+ resolveRequest({ app_context: { current_user: { distinct_id: 'user-1' } as UserType }, feature_flags: null })+ await applyDeferredAppContext()+ void window.POSTHOG_APP_CONTEXT.current_user++ expect(earlyUserContextReads()).toEqual(['current_team'])+ })+it.each([['https://us.posthog.com/project/1/insights?a=1#tab',diff --git a/frontend/src/lib/utils/deferredAppContext.ts b/frontend/src/lib/utils/deferredAppContext.tsindex 3c87ce27aa5b..862d7d5f3341 100644--- a/frontend/src/lib/utils/deferredAppContext.ts+++ b/frontend/src/lib/utils/deferredAppContext.ts@@ -17,6 +17,50 @@ declare global {}}+// The keys `add_user_app_context` in posthog/utils.py fills. A deferred page gets them only from `/_app_context`.+const USER_APP_CONTEXT_KEYS = new Set([+ 'current_user',+ 'current_team',+ 'current_project',+ 'effective_resource_access_control',+ 'resource_access_control',+ 'frontend_apps',+ 'default_event_name',+ 'has_pageview',+ 'has_screen',+ 'has_person_email',+ 'homepage',+])++let earlyReads: Set<string> | undefined+let userDataArrived = false++/**+ * Records each user data key that code reads before the data arrives, when it is still missing.+ * The boot timing event reports the keys, so a read like that shows up in production.+ */+export function watchEarlyUserContextReads(): void {+ const context = window.POSTHOG_APP_CONTEXT+ if (!window.POSTHOG_APP_CONTEXT_REQUEST || !context) {+ return+ }+ const reads = new Set<string>()+ earlyReads = reads+ userDataArrived = false+ window.POSTHOG_APP_CONTEXT = new Proxy(context, {+ get(target, key, receiver) {+ if (!userDataArrived && typeof key === 'string' && USER_APP_CONTEXT_KEYS.has(key)) {+ reads.add(key)+ }+ return Reflect.get(target, key, receiver)+ },+ })+}++export function earlyUserContextReads(): string[] {+ return [...(earlyReads ?? [])]+}+export function inlineAppContextUrl(href: string): string {const url = new URL(href)url.searchParams.set(DEFERRED_APP_CONTEXT_PARAM, '0')@@ -24,8 +68,7 @@ export function inlineAppContextUrl(href: string): string {}/**- * Adds the user's data to the app context when the page left it out. Code that reads the app context- * when its module loads must not load before this resolves.+ * Adds the user's data to the app context when the page left it out. The app must not boot before this resolves.*/export async function applyDeferredAppContext(): Promise<void> {const request = window.POSTHOG_APP_CONTEXT_REQUEST@@ -40,10 +83,12 @@ export async function applyDeferredAppContext(): Promise<void> {// The page is going away, so never let the boot continue without the user's data.return new Promise(() => {})}- window.POSTHOG_APP_CONTEXT = { ...window.POSTHOG_APP_CONTEXT, ...deferred.app_context } as AppContext+ // Merge in place, so code that kept the context object before the data arrived also gets the data.+ window.POSTHOG_APP_CONTEXT = Object.assign(window.POSTHOG_APP_CONTEXT ?? {}, deferred.app_context) as AppContext+ userDataArrived = truewindow.POSTHOG_USER_IDENTITY_WITH_FLAGS = {...window.POSTHOG_USER_IDENTITY_WITH_FLAGS,featureFlags: deferred.feature_flags,}- markBootPhase('app_context_loaded')+ markBootPhase('app_context_loaded', { early_user_context_reads: earlyUserContextReads() })}diff --git a/frontend/src/scenes/bootModules.test.ts b/frontend/src/scenes/bootModules.test.tsnew file mode 100644index 000000000000..400fc66f5354--- /dev/null+++ b/frontend/src/scenes/bootModules.test.ts@@ -0,0 +1,23 @@+import { earlyUserContextReads, watchEarlyUserContextReads } from 'lib/utils/deferredAppContext'++import type { AppContext } from '~/types'++describe('app boot modules', () => {+ afterEach(() => {+ delete window.POSTHOG_APP_CONTEXT+ delete window.POSTHOG_APP_CONTEXT_REQUEST+ })++ it('do not read the user data when they load', async () => {+ window.POSTHOG_APP_CONTEXT_REQUEST = new Promise(() => {})+ window.POSTHOG_APP_CONTEXT = { anonymous: false, deferred: true } as unknown as AppContext+ watchEarlyUserContextReads()++ await jest.isolateModulesAsync(async () => {+ await import('scenes/App')+ await import('scenes/bootApp')+ })++ expect(earlyUserContextReads()).toEqual([])+ })+})