: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
import { zipSync } from 'fflate'
import * as fs from 'fs'
import * as path from 'path'
import { commonConfig, copyRRWebWorkerFiles, createHashlessEntrypoints, esbuildBuild, isDev } from '@posthog/esbuilder'
// `TOOLBAR_PUBLIC_PATH`, when set, overrides the default `publicPath` so the
// toolbar bundle and its assets can be hosted under a versioned, content-pinned
// URL on the posthog-js CDN. Used by posthog-js's release workflow to ship a
// fully self-contained toolbar bundle. When unset, the bundle is served from
// Django `/static/`.
//
// esbuild uses this verbatim as a URL prefix, so a trailing slash is required;
// add one if the caller forgot.
const toolbarPublicPathOverride = process.env.TOOLBAR_PUBLIC_PATH
? process.env.TOOLBAR_PUBLIC_PATH.endsWith('/')
? process.env.TOOLBAR_PUBLIC_PATH
: process.env.TOOLBAR_PUBLIC_PATH + '/'
: ''
// Modules replaced with lightweight kea logic shims that satisfy connect() contracts
// without side effects. If the upstream logic adds new connect() values, the shim
// will silently return undefined — keep shims in sync when connect contracts change.
const shimmedModules = {
'scenes/userLogic': 'src/toolbar/shared/shims/userLogic.ts',
'models/membersLogic': 'src/toolbar/shared/shims/membersLogic.ts',
'scenes/sceneLogic': 'src/toolbar/shared/shims/sceneLogic.ts',
'scenes/teamLogic': 'src/toolbar/shared/shims/teamLogic.ts',
'lib/logic/featureFlagLogic': 'src/toolbar/shared/shims/featureFlagLogic.ts',
// Survey question labels load from an authenticated endpoint the toolbar can't reach, so
// the shim keeps its shared consumers (PropertyKeyInfo, taxonomy helpers) out of the app zone.
'scenes/surveys/surveyQuestionLabelsLogic': 'src/toolbar/shared/shims/surveyQuestionLabelsLogic.ts',
// The flag overview reads the feature flags API, which the toolbar can't reach, so the shim
// keeps PropertyKeyInfo out of the app zone.
'products/feature_flags/frontend/featureFlagSummaryLogic': 'src/toolbar/shared/shims/featureFlagSummaryLogic.ts',
// Not a kea shim: the toolbar's parity-tested urls duplicate (see src/toolbar/shared/urls.ts).
// Toolbar code imports it directly; this entry covers lib/ components shared with the
// app (TZLabel, Link, HeatmapEventsPanel), whose scenes/urls import would otherwise pull
// every product manifest into the bundle.
'scenes/urls': 'src/toolbar/shared/urls.ts',
}
// Modules replaced with an inert proxy that logs access in debug mode
const deniedPaths = [
'~/lib/hooks/useUploadFiles',
'~/queries/nodes/InsightViz/InsightViz',
'lib/hog',
'lib/api',
'scenes/activity/explore/EventDetails',
'scenes/web-analytics/WebAnalyticsDashboard',
'scenes/session-recordings/player/snapshot-processing/DecompressionWorkerManager.ts',
]
// PayGateMini (shipped in the toolbar) imports billingLogic, which we can't bundle because it
// pulls in app-only logics and, through scenes/billing, the app's billing scene graph.
const deniedPatterns = [/scenes\/billing/, /lib\/logic\/billing\//]
/**
* The toolbar shares lib/ code with the main app, and that code reaches app-only modules
* the toolbar must not ship. Tree shaking can't drop them (the shared packages aren't marked
* side-effect-free) and app code shouldn't contort itself for the toolbar, so imports are
* replaced at resolve time:
*
* - Shimmed modules get swapped for lightweight stand-ins (kea logics satisfying connect()
* contracts, and the parity-tested urls duplicate). These are intentional injection points:
* the toolbar genuinely needs different answers (its own team context, no scene routing)
* than the app.
* - Denied modules get replaced with an inert proxy. The deny list is kept minimal: only the
* paths a toolbar-shipped module actually reaches today (chiefly PayGateMini -> billingLogic)
* need cutting here. Regressions that reintroduce heavier dependencies are caught by the guard
* scripts rather than pre-emptively denied.
*
* The enforced invariants live in bin/check-toolbar-size.mjs (eager-chunk budget, per-file
* CloudFront limit), bin/check-toolbar-graph.mjs (boundary edges, forbidden packages, source
* budget), and bin/check-toolbar-csp-eval.mjs (no eval on customer pages).
*/
function createToolbarModulePlugin(dirname, extraDeniedPatterns = []) {
// Shims must also catch relative imports of the same modules (e.g. dataThemeLogic's
// `./teamLogic`), otherwise the real logic and its whole app graph leak into the bundle.
// Map each shimmed module's extensionless absolute path to its shim.
const shimsByAbsolutePath = new Map(
Object.entries(shimmedModules).map(([alias, shimFile]) => [
path.resolve(dirname, 'src', alias),
path.resolve(dirname, shimFile),
])
)
return {
name: 'toolbar-module-replacements',
setup(build) {
build.onResolve({ filter: /.*/ }, (args) => {
const shimFile = shimmedModules[args.path] ?? shimmedModules[args.path.replace(/^~\//, '')]
if (shimFile) {
return { path: path.resolve(dirname, shimFile) }
}
if (args.path.startsWith('.') && args.importer) {
const absolute = path
.resolve(path.dirname(args.importer), args.path)
.replace(/\.(tsx|ts|jsx|js)$/, '')
const shimPath = shimsByAbsolutePath.get(absolute)
if (shimPath) {
return { path: shimPath }
}
}
const shouldDeny =
deniedPaths.includes(args.path) ||
[...deniedPatterns, ...extraDeniedPatterns].some((pattern) => pattern.test(args.path))
if (shouldDeny) {
return { path: args.path, namespace: 'empty-module', sideEffects: false }
}
})
build.onLoad({ filter: /.*/, namespace: 'empty-module' }, (args) => {
return {
contents: `
module.exports = new Proxy({}, {
get: function(target, prop) {
// Prevent proxy from being treated as a Promise (thenable detection)
if (prop === 'then') return undefined;
// Tell bundler this is a CommonJS module, not ESM
if (prop === '__esModule') return false;
const shouldLog = window && window.posthog && window.posthog.config && window.posthog.config.debug;
if (shouldLog) {
console.warn('[TOOLBAR] Attempted to use denied module:', ${JSON.stringify(
args.path
)});
}
return function() {
return {}
}
}
});
`,
loader: 'js',
}
})
},
}
}
// The toolbar ships as two artifacts:
//
// dist/toolbar.js — a tiny classic-script loader (src/toolbar/floating/loader.ts). posthog-js
// injects it with a plain <script> tag on customer pages and calls
// window.ph_load_toolbar on load; the loader then import()s the app.
// dist/toolbar/ — the real app: an ESM entry (toolbar-app-<hash>.js, hashless copy
// alongside as a version-skew fallback) plus code-split chunks, so
// lazily-imported features are fetched on demand instead of inlined.
// dist/toolbar/toolbar-app.css — the app entry's stylesheet (hashless copy); ToolbarApp.tsx
// fetches it into the shadow root. It lives inside dist/toolbar/
// so its relative font url()s resolve against toolbar/assets/.
// dist/toolbar.css — copy at the old URL, only consumed by stale-cached single-file
// toolbar.js builds during the unversioned-deploy transition window.
//
// The loader resolves the app relative to its own script URL, and chunk imports inside the app
// are relative too, so the same artifacts work from Django /static/ on any instance and from
// the versioned/major-alias/compatibility prefixes on the posthog-js CDN (whose release
// pipeline publishes dist/toolbar/ recursively when present).
export function getToolbarAppBuildConfig(dirname) {
return {
// Named 'Toolbar' so the metafile lands at toolbar-esbuild-meta.json, which
// bin/check-toolbar-graph.mjs and bin/check-toolbar-size.mjs read.
name: 'Toolbar',
entryPoints: { 'toolbar-app': 'src/toolbar/floating/index.tsx' },
format: 'esm',
splitting: true,
outdir: path.resolve(dirname, 'dist', 'toolbar'),
chunkNames: 'chunk-[name]-[hash]',
// Shadow any AMD loader on the host page (module-scoped var, applied to every output
// file) so bundled UMD dependencies don't try to register with e.g. RequireJS.
banner: { js: 'var define = undefined;' },
// NO publicPath (explicitly overriding commonConfig's '/static'): esbuild would bake it
// into the chunk import specifiers as absolute URLs, but the same artifacts are served
// from Django /static/ on any region or self-hosted instance and from the posthog-js
// CDN prefixes — chunks must resolve relative to the importing module. Fonts stay
// file-loaded with relative url()s in the CSS (which is fetched from inside
// dist/toolbar/, so they resolve); svgs are imported from JS where a relative specifier
// string would resolve against the customer page's URL, so inline them instead.
publicPath: undefined,
loader: { ...commonConfig.loader, '.svg': 'dataurl' },
// Inject TOOLBAR_PUBLIC_PATH at build time as a bare global so runtime
// code (e.g. ToolbarApp.tsx's CSS loader) can construct URLs to sibling
// files in the same versioned bundle. The identifier is declared as
// `declare const` in frontend/src/globals.d.ts so TypeScript is happy.
// Merge with commonConfig.define so we don't drop the inherited
// `global` / `process.env.NODE_ENV` substitutions.
define: {
...commonConfig.define,
__POSTHOG_TOOLBAR_PUBLIC_PATH__: JSON.stringify(toolbarPublicPathOverride),
},
writeMetaFile: true,
extraPlugins: [createToolbarModulePlugin(dirname)],
}
}
/**
* Runs after the toolbar app build: emits the hashless entry copies, promotes the entry CSS to
* the stable dist/toolbar.css URL, and builds the loader with the hashed entry filename baked
* in. Called from build.mjs's onBuildComplete and bin/build-toolbar.mjs (including per rebuild
* in watch mode — the loader build is a single tiny file).
*/
export async function finalizeToolbarBuild(dirname, buildResponse) {
if (!buildResponse) {
return
}
const entrypoints = buildResponse.entrypoints || []
const entryJs = entrypoints.find((e) => e.endsWith('.js'))
const entryCss = entrypoints.find((e) => e.endsWith('.css'))
if (!entryJs || !entryCss) {
// Failing the build beats shipping a loader that points at nothing.
throw new Error(`Toolbar app build produced no entry ${!entryJs ? 'JS' : 'CSS'} output.`)
}
// esbuild emits per-chunk CSS: only the entry's stylesheet is loaded into the shadow root
// (as toolbar.css), so toolbar features must keep their styles statically imported. Chunk
// CSS files are dead weight from lazily-imported app scenes, not a correctness problem.
// toolbar-app-<hash>.js -> toolbar-app.js next to it: the loader's version-skew fallback.
createHashlessEntrypoints(dirname, entrypoints)
// The copy lives one directory up from the entry CSS, so point its sourceMappingURL back
// into dist/toolbar/ — collectstatic fails on a sourcemap reference it can't resolve.
const entryCssContent = fs
.readFileSync(entryCss, 'utf8')
.replace(/sourceMappingURL=([^\s*]+\.css\.map)/, 'sourceMappingURL=toolbar/$1')
fs.writeFileSync(path.resolve(dirname, 'dist', 'toolbar.css'), entryCssContent)
// The chunks bundle rrweb, whose inlined worker string carries a sourceMappingURL that
// collectstatic resolves relative to dist/toolbar/ — the map must exist there too.
copyRRWebWorkerFiles(dirname, 'dist/toolbar')
await esbuildBuild({
absWorkingDir: dirname,
entryPoints: ['src/toolbar/floating/loader.ts'],
bundle: true,
// ESM output keeps the runtime-dynamic import() untouched; with no static
// imports/exports of its own, the file still parses as a classic script.
format: 'esm',
outfile: path.resolve(dirname, 'dist', 'toolbar.js'),
minify: !isDev,
sourcemap: true,
target: commonConfig.target,
tsconfig: commonConfig.tsconfig,
define: {
...commonConfig.define,
__POSTHOG_TOOLBAR_PUBLIC_PATH__: JSON.stringify(toolbarPublicPathOverride),
__POSTHOG_TOOLBAR_APP_ENTRY__: JSON.stringify(path.basename(entryJs)),
},
})
}
// The browser extension ships as a folder to load unpacked in Chrome, and as a zip for the Chrome Web Store:
//
// dist/toolbar-extension/chrome/manifest.json
// dist/toolbar-extension/chrome/panel.html, panel.js, panel.css, background.js, content.js, content.css,
// assets/, icons/
// dist/toolbar-extension/posthog-toolbar-chrome-<version>.zip
const TOOLBAR_EXTENSION_OUT_DIR = 'toolbar-extension'
const TOOLBAR_EXTENSION_VERSION = '0.1.0'
const TOOLBAR_EXTENSION_BUILD_DIR = 'toolbar-extension-build'
const TOOLBAR_EXTENSION_ICONS = {
16: 'icons/favicon-16x16.png',
32: 'icons/favicon-32x32.png',
128: 'icons/posthog-128x128.png',
192: 'icons/android-chrome-192x192.png',
}
export function cleanToolbarExtensionBuild(dirname) {
fs.rmSync(path.resolve(dirname, 'dist', TOOLBAR_EXTENSION_BUILD_DIR), { recursive: true, force: true })
}
/** panel.html isn't an esbuild input, so watch mode rebuilds on its edits only through this. */
function watchExtensionPagesPlugin(dirname) {
return {
name: 'watch-toolbar-extension-pages',
setup(build) {
build.onLoad({ filter: /extension[\\/]panel\.tsx$/ }, (args) => ({
contents: fs.readFileSync(args.path, 'utf8'),
loader: 'tsx',
watchFiles: [path.resolve(dirname, 'src/toolbar/extension/panel.html')],
}))
},
}
}
function toolbarExtensionBaseConfig(dirname) {
return {
outdir: path.resolve(dirname, 'dist', TOOLBAR_EXTENSION_BUILD_DIR),
// The pages and scripts name their files directly, so they carry no hash.
entryNames: '[name]',
// Extension pages resolve assets against their own folder, so URLs stay relative.
publicPath: undefined,
loader: { ...commonConfig.loader, '.svg': 'dataurl' },
define: {
...commonConfig.define,
__POSTHOG_TOOLBAR_PUBLIC_PATH__: JSON.stringify(''),
},
}
}
export function getToolbarExtensionBuildConfig(dirname) {
return {
...toolbarExtensionBaseConfig(dirname),
name: 'Toolbar extension',
entryPoints: { panel: 'src/toolbar/extension/panel.tsx' },
format: 'esm',
// Keeps lazily imported code (such as hedgehog mode, reached through lemon-ui) out of panel.js.
splitting: true,
chunkNames: 'chunks/[name]-[hash]',
extraPlugins: [createToolbarModulePlugin(dirname), watchExtensionPagesPlugin(dirname)],
}
}
/**
* The panel injects content.js into the tab with `scripting.executeScript`, which runs a file as a classic script, and
* the manifest loads background.js as a classic service worker. So each of these scripts is one self-contained IIFE.
*/
export function getToolbarExtensionScriptsBuildConfig(dirname) {
return {
...toolbarExtensionBaseConfig(dirname),
name: 'Toolbar extension scripts',
entryPoints: {
background: 'src/toolbar/extension/background.ts',
content: 'src/toolbar/extension/content.tsx',
'page-agent': 'src/toolbar/extension/pageAgent.ts',
},
format: 'iife',
splitting: false,
// An IIFE inlines every lazy import. The content script never runs hedgehog mode (pixi needs `new Function`,
// which Manifest V3 forbids) or the product tours editor, so they stay out of every page it's injected into.
extraPlugins: [
createToolbarModulePlugin(dirname, [
/^@posthog\/hedgehog-mode$/,
/product-tours\/editor\/generateStepHtml$/,
]),
],
}
}
// Asks for every http and https site, because the panel follows the active tab without a click on the extension
// button, which `activeTab` needs.
function buildToolbarExtensionManifest() {
return {
manifest_version: 3,
name: 'PostHog',
description: 'Use the PostHog toolbar in a side panel next to your website.',
version: TOOLBAR_EXTENSION_VERSION,
icons: TOOLBAR_EXTENSION_ICONS,
action: {
default_title: 'Open PostHog',
default_icon: TOOLBAR_EXTENSION_ICONS,
},
permissions: ['scripting', 'storage', 'sidePanel'],
host_permissions: ['http://*/*', 'https://*/*'],
web_accessible_resources: [{ resources: ['content.css', 'assets/*'], matches: ['http://*/*', 'https://*/*'] }],
side_panel: { default_path: 'panel.html' },
// 116 is the first release with `sidePanel.setPanelBehavior`, which opens the panel from the toolbar button.
minimum_chrome_version: '116',
background: { service_worker: 'background.js' },
}
}
export function finalizeToolbarExtensionBuild(dirname) {
const buildDir = path.resolve(dirname, 'dist', TOOLBAR_EXTENSION_BUILD_DIR)
const extensionDir = path.resolve(dirname, 'dist', TOOLBAR_EXTENSION_OUT_DIR)
const outDir = path.resolve(extensionDir, 'chrome')
fs.rmSync(extensionDir, { recursive: true, force: true })
fs.cpSync(buildDir, outDir, { recursive: true })
fs.copyFileSync(path.resolve(dirname, 'src/toolbar/extension/panel.html'), path.resolve(outDir, 'panel.html'))
for (const icon of Object.values(TOOLBAR_EXTENSION_ICONS)) {
fs.mkdirSync(path.dirname(path.resolve(outDir, icon)), { recursive: true })
fs.copyFileSync(path.resolve(dirname, 'public', icon), path.resolve(outDir, icon))
}
fs.writeFileSync(
path.resolve(outDir, 'manifest.json'),
JSON.stringify(buildToolbarExtensionManifest(), null, 4) + '\n'
)
fs.writeFileSync(
path.resolve(extensionDir, `posthog-toolbar-chrome-${TOOLBAR_EXTENSION_VERSION}.zip`),
zipSync(readDirectoryFiles(outDir))
)
}
function readDirectoryFiles(directory) {
const files = {}
for (const entry of fs.readdirSync(directory, { recursive: true, withFileTypes: true })) {
// Source maps stay in the unpacked folders for local debugging, but would triple the size of the zips.
if (entry.isFile() && !entry.name.endsWith('.map')) {
const filePath = path.join(entry.parentPath, entry.name)
files[path.relative(directory, filePath).split(path.sep).join('/')] = fs.readFileSync(filePath)
}
}
return files
}