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.

5.8 KB
Raw Blame
import type { PostHog } from 'posthog-js'

import type { ToolbarParams } from '~/types'

// The toolbar loader: a tiny classic script served as /static/toolbar.js. posthog-js (every
// version, forever) injects it with a plain <script> tag and calls window.ph_load_toolbar on
// the script's load event — that contract must never change. This file defines those globals
// synchronously, then dynamic-import()s the real toolbar app (an ESM entry with code-split
// chunks under ./toolbar/) the first time the toolbar actually loads.
//
// Rules for this file:
// - No value imports (type imports are fine — they're erased). Anything bundled here ships on
//   every toolbar load before a single feature runs; app code belongs in the ESM entry.
//   check-toolbar-size.mjs caps this file's size to keep that honest.
// - No eval / new Function — customer pages run strict CSPs; check-toolbar-csp-eval.mjs
//   asserts zero violations for this file.
// - Resolve chunks relative to the script's own URL, never an absolute host: the same
//   artifacts are served from Django /static/ on any region or self-hosted instance, and from
//   the versioned, major-alias and compatibility prefixes on the posthog-js CDN.

type ToolbarModule = typeof import('~/toolbar/floating/index')

// document.currentScript is only set during the initial synchronous evaluation, so capture it
// at module scope. It is null when the loader is evaluated as a module (tests) — then the
// build-time public path (set for posthog-js versioned CDN bundles) is the fallback.
const scriptSrc = (document.currentScript as HTMLScriptElement | null)?.src

// Share the origin the loader was served from with the app bundle. The app (ToolbarApp) is a
// separately imported module and cannot read document.currentScript once it renders, so it
// resolves its own sibling assets - the stylesheet - from this value. It follows the same
// reverse proxy as the JS this way, instead of the baked absolute CDN host.
;(window as any).__POSTHOG_TOOLBAR_SCRIPT_SRC__ = scriptSrc

function resolveAppUrl(fileName: string): string {
    const base = scriptSrc || __POSTHOG_TOOLBAR_PUBLIC_PATH__
    if (!base) {
        throw new Error('PostHog toolbar loader could not determine its own URL')
    }
    return new URL(`toolbar/${fileName}`, base).href
}

async function importWithRetry(url: string, retries: number, delayMs: number): Promise<ToolbarModule> {
    try {
        return await import(url)
    } catch (error) {
        if (retries <= 0) {
            throw error
        }
        await new Promise((resolve) => setTimeout(resolve, delayMs))
        return importWithRetry(url, retries - 1, delayMs * 2)
    }
}

let appPromise: Promise<ToolbarModule> | null = null

function loadApp(): Promise<ToolbarModule> {
    if (!appPromise) {
        appPromise = importWithRetry(resolveAppUrl(__POSTHOG_TOOLBAR_APP_ENTRY__), 2, 300)
            .catch(() => {
                // Version-skew fallback: a cached loader can reference a hashed entry that no
                // longer exists on the origin after a deploy. The hashless copy always points at
                // the latest build, whose chunk references are self-consistent. Same 5-minute
                // cache bucket as the toolbar.css loader.
                const fiveMinutesInMillis = 5 * 60 * 1000
                const cacheBuster = Math.floor(Date.now() / fiveMinutesInMillis) * fiveMinutesInMillis
                // Retried too: reaching here doesn't mean the network is healthy — the primary
                // import may have failed on a transient error rather than a version-skew 404.
                return importWithRetry(resolveAppUrl(`toolbar-app.js?t=${cacheBuster}`), 2, 300)
            })
            .then((module) => {
                controllerDelegate = module.posthogToolbarController
                return module
            })
            .catch((error) => {
                appPromise = null // a later ph_load_toolbar call gets a fresh attempt
                throw error
            })
    }
    return appPromise
}

// The app module exposes the real window.posthogToolbarController when it evaluates, but
// third-party code may grab the global right after the loader script loads — give those early
// consumers a stub that starts forwarding once the app is in.
let controllerDelegate: ToolbarModule['posthogToolbarController'] | null = null
const controllerStub = {
    get isLoaded(): boolean {
        return controllerDelegate ? controllerDelegate.isLoaded : false
    },
    get isVisible(): boolean {
        return controllerDelegate ? controllerDelegate.isVisible : false
    },
    get isAuthenticated(): boolean {
        return controllerDelegate ? controllerDelegate.isAuthenticated : false
    },
    show(): void {
        controllerDelegate?.show()
    },
    hide(): void {
        controllerDelegate?.hide()
    },
    authenticate(): void {
        controllerDelegate?.authenticate()
    },
    destroy(): void {
        controllerDelegate?.destroy()
    },
}

const win = window as any

win['posthogToolbarController'] = win['posthogToolbarController'] || controllerStub

win['ph_load_toolbar'] = async function (toolbarParams: ToolbarParams, posthog?: PostHog): Promise<void> {
    // Start the load-duration clock before the app module and its chunks are fetched — the
    // fetch is part of what the user waits for. loadToolbar keeps the earliest timestamp.
    win.__posthog_toolbar_load_start = performance.now()
    let module: ToolbarModule
    try {
        module = await loadApp()
    } catch (error) {
        // Graceful degradation is "no toolbar", never a broken host page.
        console.warn('[PostHog Toolbar] Failed to load the toolbar bundle', error)
        return
    }
    await module.loadToolbar(toolbarParams, posthog)
}

/** @deprecated, use "ph_load_toolbar" instead */
win['ph_load_editor'] = win['ph_load_toolbar']