Skip to content

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

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.tsx
index 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.__posthogAppRoot
delete window.ESBUILD_CSS_READY
+ delete window.POSTHOG_APP_CONTEXT_REQUEST
document.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_READY
diff --git a/frontend/src/index.tsx b/frontend/src/index.tsx
index 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> | undefined
function 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.ts
index 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?: boolean
deferred_app_context?: boolean
deferred_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.ts
index 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_CONTEXT
await 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.ts
index 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 = true
window.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.ts
new file mode 100644
index 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([])
+ })
+})