Skip to content

build: download the PostHog bootstrap on each build - #21670

Merged
marandaneto merged 11 commits into
masterfrom
chore/use-posthog-script-loader
Nov 2, 2026
Merged

marandaneto merged 11 commits into
masterfrom
chore/use-posthog-script-loader

Conversation

@marandaneto

@marandaneto marandaneto commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Executive summary

Download the published PostHog bootstrap during every Gatsby build, then serve it locally before Gatsby starts. Fetch the current major-1 release instead of committing a vendored copy. Keep the existing SDK initialization, callbacks, and asynchronous full-SDK download.

PostHog/posthog-js#5470 is merged and released. The required loader-bootstrap.js artifact is available from the release CDN. The previous release gate and temporary vendor provenance no longer apply.

🗺️ PR tour

1. Fetch the bootstrap before publishing (build diff)

gatsby/onPreBootstrap.ts downloads https://us-assets.i.posthog.com/static/1/loader-bootstrap.js whenever analytics is configured. POSTHOG_BOOTSTRAP_URL names the region-independent release artifact. Runtime regions and proxies remain separate, selected by data-asset-host. The test keeps an independent expected URL. An uncached Request also bypasses the existing URL-only development cache. Each attempt has a 30-second timeout. HTTP 408/429/5xx, network failures, and interrupted body reads get up to three attempts, with 500 ms and 1 s delays. Other HTTP errors and empty content fail immediately. Exhausted retries stop the build instead of publishing stale code.

async function downloadPostHogBootstrap(): Promise<string> {
for (let attempt = 0; ; attempt++) {
let retryable = true
try {
// A Request bypasses the URL-only development cache for this mutable asset.
const response = await fetch(
new Request(POSTHOG_BOOTSTRAP_URL, {
cache: 'no-store',
signal: AbortSignal.timeout(30000),
})
)
if (!response.ok) {
retryable = response.status === 408 || response.status === 429 || response.status >= 500
await response.body?.cancel()
throw new Error(`Unable to download PostHog bootstrap: HTTP ${response.status}`)
}
const bootstrap = (await response.text()).replace(/\n\/\/# sourceMappingURL=.*\s*$/, '\n')
retryable = false
if (!bootstrap.trim()) {
throw new Error('Downloaded PostHog bootstrap is empty')
}
return bootstrap
} catch (error) {
if (!retryable || attempt === 2) throw error
await delay(500 * 2 ** attempt)
}
}
}

The hook removes only the trailing source-map comment and writes static/scripts/posthog-bootstrap.js beside the existing generated init script. .gitignore excludes this generated file. The vendored file and its provenance record are removed from the PR. The embedded handwritten bootstrap is also removed from the generated initialization code. All initialization settings remain intact.

2. Keep application startup independent of the analytics host (diff)

src/html.tsx loads the local bootstrap and init script after server-rendered content, before Gatsby's async bundles. The local bootstrap creates the queue synchronously and downloads the full SDK asynchronously. data-asset-host keeps the runtime host configuration, while data-sdk-version="1" preserves same-major SDK updates.

posthog.com/src/html.tsx

Lines 44 to 61 in d5c7b4f

{props.preBodyComponents}
{/* nosemgrep: typescript.react.security.audit.react-dangerouslysetinnerhtml.react-dangerouslysetinnerhtml - Gatsby body content from build, not user input */}
<div key={`body`} id="___gatsby" dangerouslySetInnerHTML={{ __html: props.body }} />
{/* Create the local queue before Gatsby starts without waiting for the analytics host. */}
{process.env.GATSBY_POSTHOG_API_KEY && process.env.GATSBY_POSTHOG_API_HOST && (
<>
<script
src="/scripts/posthog-bootstrap.js"
data-asset-host={
process.env.GATSBY_POSTHOG_ASSET_HOST || process.env.GATSBY_POSTHOG_API_HOST
}
data-sdk-version="1"
/>
<script src="/scripts/posthog-init.js" />
</>
)}
{props.postBodyComponents}
</body>

3. Wait for the current initialized SDK (diff)

useEarlyAccessFeatures reads the current window.posthog on each attempt and checks __loaded. It does not retain a discarded queue for survey callbacks. Polling and the six-second fallback remain unchanged.

const stagesKey = JSON.stringify(stages)
const fetchFeatures = useCallback(() => {
const posthog = typeof window !== 'undefined' ? window.posthog : undefined
if (!posthog?.__loaded || typeof posthog.getEarlyAccessFeatures !== 'function') {
return false
}

4. Test generation, startup, and fallback behavior (loader tests)

scripts/posthog-loader.test.cjs has 20 cases. It checks fresh downloads across repeated builds, transient recovery, bounded retry exhaustion, permanent failures, disabled analytics, HTML ordering, initialization settings, and application startup. The browser case now obtains the real published bootstrap through the build hook instead of reading a vendored file. It holds the remote SDK response and confirms that an async app probe remains usable and queues its capture.

for (const [name, failure] of [
...[408, 429, 503].map((status) => [`HTTP ${status}`, () => new Response('unavailable', { status })]),
[
'connection reset',
() => {
throw new TypeError('fetch failed: connection reset')
},
],
[
'timeout',
() => {
throw new DOMException('The operation timed out', 'TimeoutError')
},
],
[
'response body failure',
() =>
new Response(
new ReadableStream({
start(controller) {
controller.error(new TypeError('connection reset while reading body'))
},
})
),
],
]) {
test(`a build retries ${name} with bounded backoff and publishes only a fresh bootstrap`, async () => {
const writes = new Map([['posthog-bootstrap.js', 'stale bootstrap']])
const requests = []
const waits = []
await generatedInit(
env,
async (request) => {
requests.push(request)
assert.equal(request.cache, 'no-store')
assert.equal(request.signal.aborted, false)
assert.equal(writes.get('posthog-bootstrap.js'), 'stale bootstrap')
assert.equal(writes.has('posthog-init.js'), false)
return requests.length < 3 ? failure() : new Response('window.bootstrapVersion = "fresh";')
},
writes,
waits
)
assert.equal(requests.length, 3)
assert.equal(new Set(requests.map((request) => request.signal)).size, 3)
assert.deepEqual(waits, [500, 1000])
assert.equal(writes.get('posthog-bootstrap.js'), 'window.bootstrapVersion = "fresh";')
assert.equal(writes.has('posthog-init.js'), true)
})
}
for (const [name, download, message, attempts] of [
['HTTP failure', async () => new Response('unavailable', { status: 503 }), /503/, 3],
['permanent HTTP failure', async () => new Response('not found', { status: 404 }), /404/, 1],
['empty response', async () => new Response(' \n'), /empty/i, 1],
[
'network failure',
async () => {
throw new Error('network unavailable')
},
/network unavailable/,
3,
],
]) {
test(`a build fails instead of keeping a stale bootstrap after ${name}`, async () => {
const writes = new Map([['posthog-bootstrap.js', 'stale bootstrap']])
const waits = []
let requests = 0
await assert.rejects(
generatedInit(
env,
async () => {
requests++
return download()
},
writes,
waits
),
message
)
assert.equal(requests, attempts)
assert.deepEqual(waits, attempts === 3 ? [500, 1000] : [])
assert.equal(writes.get('posthog-bootstrap.js'), 'stale bootstrap')
assert.equal(writes.has('posthog-init.js'), false)
})
}

scripts/early-access-features.test.cjs retains four SDK-readiness and fallback cases. Its dependency map contains only the hook's actual imports, without the obsolete usePostHog setup. package.json adds pnpm test:posthog-loader. The preview workflow runs all 24 cases before building the site.

The retained startup test uses an inert core response. It proves startup and queuing, not full SDK replay. Separate real-SDK checks are recorded below.

🔍 Reviewer's guide

Testing done

Check Command / method Result
Release availability curl -fsS on US /static/1/loader-bootstrap.js, US /static/loader-bootstrap.js, and EU /static/1/loader-bootstrap.js. All returned HTTP 200, 4,626 bytes. SDK #5470 is merged.
Baseline Node 22 and Brave: pnpm test:posthog-loader before edits. All 12 previous cases passed.
Red-green proof Ran final download tests against an isolated copy of the pre-change build hook, then the new hook. Before: stale bytes remained, and HTTP, empty-response, and network failures did not reject. Four expected failures. After: all pass. Both disabled-analytics controls pass.
Retry red-green proof pnpm exec node --test --test-name-pattern='a build retries|a build fails' scripts/posthog-loader.test.cjs Before: eight expected failures on 7541920846; recoverable errors aborted immediately, and exhaustion made only one attempt. The 404 and empty-content controls passed. After: all ten pass.
Loader and hook tests PUPPETEER_EXECUTABLE_PATH="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" pnpm test:posthog-loader All 24 passed. The browser case used a dedicated temporary Brave profile and the real published artifact.
Nearby tests pnpm test:gatsby-functions, pnpm test:pocket-guides, pnpm test:twig-integration 4, 7, and 6 passed. Total: 41 local tests.
Previous real build-hook output (7541920846) Started pnpm start; compared its generated bootstrap with the released artifact after source-map removal. Exact match, 4,582 generated bytes. No vendored artifact remains tracked.
Previous full application and SDK (7541920846) Brave on /, /docs, and /roadmap, with SDK 1.443.0 held during hydration. Compared the downloaded bootstrap with the previous vendor through request interception. Six checks passed. All routes hydrated and queued calls before release. The real SDK then initialized, and local mocked ingestion returned 200. No intermediate hosted loader, page exceptions, or new console errors. Existing development-only 404 and SVG-width messages remain in both versions.
Static cleanup validation Ran all 24 analytics cases before and after naming the release URL and removing the unused hook stub. Reran all 17 nearby tests. All passed. No behavioral fix or new red-green test is claimed for this cleanup. No assertions were removed.
Formatting and syntax Scoped pnpm exec prettier --write / --check; pnpm exec node --check scripts/posthog-loader.test.cjs; git diff --check. Passed. Generated SDK bytes are not formatted.
Test authoring audit Inspected all 24 cases, helpers, and CI routing. Replaced obsolete vendor-integrity coverage with download coverage. Retained startup and readiness coverage. Verified the original four download failures and the eight new retry failures before their fixes. Retained existing assertions and added retry recovery, exhaustion, and permanent-failure coverage. The static cleanup removes only unused setup and keeps strict dependency checking.
Deslop and autoreview Diff-scoped inspection; autoreview --mode branch --base origin/master --prompt-file .cache/posthog-bootstrap-maintenance-review-notes.md. No cleanup needed. TruffleHog passed. No actionable findings on d5c7b4f0c33bb54c25512851bbb708348c1a49bd.
Sync and signatures Merged current master without rewriting history. Queried GitHub commit verification. No conflicts. Build update, both merge commits, the retry commit, and the static cleanup commit are verified.
CI Checks for d5c7b4f0c33bb54c25512851bbb708348c1a49bd. All checks passed or were skipped: 20 passed, one skipped. The analytics suite, production build, and preview deployment passed.
Deployed preview (d5c7b4f0c3) curl on the generated script, then Brave on /, /docs, and /roadmap at the preview. Compared the previous vendor and downloaded bootstrap in fresh isolated contexts. The served script exactly matches the 4,582-byte generated release artifact. All three routes return HTTP 200, mount React, and initialize the SDK with no hosted-loader request. Home and docs have no uncaught exceptions in either control. Roadmap has the same seven React hydration errors (#418 and #423) with both bootstraps.

The full-application check used the actual generated file served by the restarted dev server. Only the previous-vendor control response was intercepted. Its ingestion endpoint used a dummy token and a local mock, not production ingestion. The retained browser test and the full-app checks use separate temporary Brave profiles, not working browser tabs.

Preview POST requests were fulfilled locally to avoid sending production telemetry. An initial preview check also saw hydration errors on the home page. The isolated comparison did not reproduce them there, and reproduced identical roadmap errors with both bootstrap versions. These warnings are not reported as fixed by this PR.

Not tested locally: a production build with production credentials and every shared-shell route. The CI production build and deployed preview for the static cleanup passed their checks above. No page layout, styling, or content changed in this PR. No pages moved.

What to look at

  1. Build-time download: publication depends on the release CDN being available within three attempts. Transient failures get bounded backoff. Permanent failures and retry exhaustion stop the build. There is no stale-file fallback.
  2. Local ordering: the local queue and init must precede Gatsby. Only the remote SDK download is asynchronous. Runtime region and proxy settings still come from data-asset-host.
  3. SDK readiness: queued methods are not initialized methods. Keep the current-instance lookup and fallback timer.

Changes

Replace the embedded bootstrap with the SDK-maintained local bootstrap, fetched afresh during each build. Remove the temporary vendor and provenance record. Preserve initialization, application startup, and roadmap fallback behavior.

Checklist

  • SDK YouTube-style art for the "Developer marketing for startups" post #5470 is merged and the published bootstrap is accessible.
  • Every configured Gatsby build downloads the current major-1 bootstrap.
  • Generated bootstrap is ignored instead of vendored.
  • American English and relative internal website URLs.
  • Scoped formatting, tests, and authoring audit complete.
  • Static-cleanup CI and deployed preview checked. Existing roadmap hydration errors are recorded above.
  • No page moves or redirects in the PR diff.

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 02, 2026 10:44AM

@marandaneto
marandaneto requested a review from a team October 28, 2026 09:35
@marandaneto
marandaneto marked this pull request as ready for review October 28, 2026 09:36
@marandaneto
marandaneto requested a review from a team as a code owner October 28, 2026 09:36

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 60e0a25: 1 Must fix, 2 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Comment thread src/html.tsx Resolved
Comment thread src/html.tsx Resolved
Comment thread src/html.tsx Resolved
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

10.53 MiB (+1.5 KiB / +0.0%)

Largest changed named chunks
Chunk Gzip Δ vs master
posthog-bootstrap.js 2.0 KiB new

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 20.89 MiB (+1.9 KiB / +0.0%) report-only 2119
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1465.2 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 840.9 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs 481.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs 450.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs 385.8 KiB
./src/hooks/useCustomers.tsx + 61 modules 381.8 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/tourist.mjs 364.6 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 130 modules 314.3 KiB
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules 287.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs 284.1 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@marandaneto

Copy link
Copy Markdown
Member Author
Screenshot 2026-10-28 at 11 00 14

tested locally

@dustinbyrne dustinbyrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The configuration and roadmap readiness changes check out. One availability concern remains: a stalled analytics loader now delays Gatsby startup and React-driven interactions, even though SSR content paints. Details are inline.

AI-assisted review.

Comment thread src/html.tsx Resolved
@marandaneto marandaneto changed the title chore: use the hosted PostHog script loader chore: use the local PostHog SDK bootstrap Oct 29, 2026
@marandaneto marandaneto changed the title chore: use the local PostHog SDK bootstrap build: download the PostHog bootstrap on each build Oct 30, 2026
@marandaneto
marandaneto marked this pull request as ready for review October 30, 2026 12:59

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 7541920: 1 Should fix.

Comment thread gatsby/onPreBootstrap.ts Resolved

@ioannisj ioannisj left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 An AI agent wrote this on behalf of @ioannisj.

Nothing blocking, three small maintainability items: the bootstrap URL is hard-coded in gatsby/onPreBootstrap.ts while the asset host is env-driven everywhere else, the two new test files duplicate the same TS loader helper, and one test still stubs an import the hook dropped. The download, retry, and script-ordering paths read correct to me.

Comment thread gatsby/onPreBootstrap.ts Resolved
else Reflect.deleteProperty(globalThis, key)
}
})
const load = (file, dependencies) => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 An AI agent wrote this on behalf of @ioannisj.

[suggestion] Small one: both new test files carry the same load helper (read the file, ts.transpileModule to CommonJS, runInNewContext with a stubbed require), and they already drift a bit, this one asserts on unexpected deps while the loader test falls through to the real require. Worth a shared scripts/test-utils/load-ts-module.cjs with the strict-deps check as an option, so the next hook test doesn't add a third copy? Or better as a follow-up?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can be a follow up

Comment thread scripts/early-access-features.test.cjs Resolved
…cript-loader

# Conflicts:
#	.github/workflows/deploy-preview.yml
@marandaneto
marandaneto enabled auto-merge (squash) November 2, 2026 10:40
@marandaneto
marandaneto merged commit e81f2c2 into master Nov 2, 2026
21 checks passed
@marandaneto
marandaneto deleted the chore/use-posthog-script-loader branch November 2, 2026 10:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants