From 14887ab0fa2d3c4d3809e108b215ef5f8e621f0f Mon Sep 17 00:00:00 2001 From: Muhammad Sohail Date: Thu, 19 Nov 2026 13:08:49 +0500 Subject: [PATCH] fix(portal): load custom scripts once the page is ready, so they can change it A listed script ran as soon as the portal's code started, before React had hydrated the page. One that added an element to the header or the article made hydration fail with React error #418: React threw the whole prerendered page away and built it again, without the element. Only elements added to survived, since React skips unknown nodes there. The Google tags still start at once. The listed scripts now wait for loadScripts(), which ListedScripts calls from its effect. It renders in the same Suspense boundary as each page's content, which React hydrates last, so the effect runs once the whole page is React's. Reported in apimatic/apimatic-io#2357. Co-Authored-By: Claude Opus 5.5 --- .../src/components/listed-scripts.tsx | 10 ++++ portal-template/src/components/not-found.tsx | 2 + portal-template/src/lib/analytics.ts | 13 +++- portal-template/src/routes/$.tsx | 17 ++++-- test/portal-template/analytics.test.ts | 60 ++++++++++++++++--- 5 files changed, 84 insertions(+), 18 deletions(-) create mode 100644 portal-template/src/components/listed-scripts.tsx diff --git a/portal-template/src/components/listed-scripts.tsx b/portal-template/src/components/listed-scripts.tsx new file mode 100644 index 000000000..d662e7719 --- /dev/null +++ b/portal-template/src/components/listed-scripts.tsx @@ -0,0 +1,10 @@ +import { useEffect } from 'react'; +import { analytics } from '@/lib/portal-analytics'; + +/** Rendered with a page's content, so its effect runs once React has hydrated the page a script may change. */ +export function ListedScripts() { + useEffect(() => { + analytics.loadScripts(); + }, []); + return null; +} diff --git a/portal-template/src/components/not-found.tsx b/portal-template/src/components/not-found.tsx index 3eba7d789..e62de595d 100644 --- a/portal-template/src/components/not-found.tsx +++ b/portal-template/src/components/not-found.tsx @@ -4,6 +4,7 @@ import { baseOptions } from '@/lib/layout.shared'; import { analytics } from '@/lib/portal-analytics'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { DefaultNotFound } from 'fumadocs-ui/layouts/home/not-found'; +import { ListedScripts } from './listed-scripts'; export function NotFound() { // The path the router has settled on: its location alone already names the page a reader is leaving this one for. @@ -18,6 +19,7 @@ export function NotFound() { return ( + ); } diff --git a/portal-template/src/lib/analytics.ts b/portal-template/src/lib/analytics.ts index 148d65e53..56a4cd4cd 100644 --- a/portal-template/src/lib/analytics.ts +++ b/portal-template/src/lib/analytics.ts @@ -122,7 +122,14 @@ export class Analytics { throw error; }); } - insertTags(this.live, this.scripts, inserted); + // The listed scripts wait for `loadScripts()`: React drops a change one makes to the page before it hydrates. + insertTags(this.live, [], inserted); + } + + /** From `ListedScripts`, once the page has hydrated. */ + public loadScripts(): void { + const inserted = this.windowAnalytics?.inserted; + if (inserted !== undefined) insertTags([], this.scripts, inserted); } /** `href` is the page the event belongs to, when the caller saw the address move on first. */ @@ -142,8 +149,8 @@ export class Analytics { public reportPageView(): void { if (isOAuthCallbackPath(window.location.pathname)) return; const inserted = this.windowAnalytics?.inserted; - // The tags and scripts a start on the OAuth callback left out, now that the reader has moved on from it. - if (inserted !== undefined) insertTags(this.live, this.scripts, inserted); + // The tags a start on the OAuth callback left out, now that the reader has moved on from it. + if (inserted !== undefined) insertTags(this.live, [], inserted); const page = pageLocation(window.location.href, this.settings.keepQueryParams); if (page === this.lastPageView) return; this.previousPageView = this.lastPageView; diff --git a/portal-template/src/routes/$.tsx b/portal-template/src/routes/$.tsx index b884d8804..1e85470f5 100644 --- a/portal-template/src/routes/$.tsx +++ b/portal-template/src/routes/$.tsx @@ -17,6 +17,7 @@ import { getMDXComponents } from '@/components/mdx'; import { OpenAPIPage } from '@/components/api-page'; import { MarkdownCopyButton } from '@/components/markdown-copy-button'; import { slimOpenAPIPageProps } from '@/lib/openapi-slim'; +import { ListedScripts } from '@/components/listed-scripts'; const rootRoute = getRouteApi('__root__'); @@ -186,12 +187,16 @@ function Page() { ); } else { - content = ( - - - - ); + content = ; } - return {content}; + return ( + + {/* One boundary for every page's content: React hydrates it last, and ListedScripts with it, never before it. */} + + {content} + + + + ); } diff --git a/test/portal-template/analytics.test.ts b/test/portal-template/analytics.test.ts index c44d685d0..876bd3eca 100644 --- a/test/portal-template/analytics.test.ts +++ b/test/portal-template/analytics.test.ts @@ -580,10 +580,27 @@ describe('Analytics', () => { const WIDGET = 'https://cdn.example.com/widget.js'; const listed: PortalScript[] = [{ src: SETUP }, { src: WIDGET }]; + // React drops a change a script makes to the page before it has hydrated, which loadScripts() waits for. + it('inserts none on a start or a page view, and all once loadScripts() is called', () => { + const page = browser(quickstart); + const analytics = new Analytics(withGtm(), listed); + + analytics.start(); + analytics.reportPageView(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT]); + + analytics.loadScripts(); + + expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); + }); + it('inserts each after the vendor tags, in the order listed, and not async, so they run in that order', () => { const page = browser(quickstart); + const analytics = new Analytics(withBoth, listed); - new Analytics(withBoth, listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map(({ src, async }) => [src, async])).to.deep.equal([ [GTM_SCRIPT, true], @@ -595,8 +612,10 @@ describe('Analytics', () => { it('inserts them on a portal with neither vendor set', () => { const page = browser(quickstart); + const analytics = new Analytics(none, listed); - new Analytics(none, listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP, WIDGET]); }); @@ -605,7 +624,10 @@ describe('Analytics', () => { it("inserts a file of the portal's own by its path from the root, and an address as it is", () => { const page = browser(quickstart); - new Analytics(none, [{ src: '/js/widget.js' }, { src: WIDGET }]).start(); + const analytics = new Analytics(none, [{ src: '/js/widget.js' }, { src: WIDGET }]); + + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal(['/js/widget.js', WIDGET]); }); @@ -618,6 +640,7 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP]); }); @@ -626,12 +649,16 @@ describe('Analytics', () => { const page = browser(quickstart); const twice = [...listed, { src: SETUP }]; const analytics = new Analytics(withGtm(), twice); + const second = new Analytics(withGtm(), twice); analytics.start(); + analytics.loadScripts(); analytics.reportPageView(); page.go('https://docs.test/guides/errors', 'Errors | Acme API'); analytics.reportPageView(); - new Analytics(withGtm(), twice).start(); + analytics.loadScripts(); + second.start(); + second.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); expect(page.reloads()).to.equal(0); @@ -641,13 +668,17 @@ describe('Analytics', () => { it('inserts none again once its element has left the page, on a new page or for a second instance', () => { const page = browser(quickstart); const analytics = new Analytics(withGtm(), listed); + const second = new Analytics(withGtm(), listed); analytics.start(); + analytics.loadScripts(); page.scripts.length = 0; analytics.reportPageView(); page.go('https://docs.test/guides/errors', 'Errors | Acme API'); analytics.reportPageView(); - new Analytics(withGtm(), listed).start(); + analytics.loadScripts(); + second.start(); + second.loadScripts(); expect(page.scripts).to.be.empty; }); @@ -659,11 +690,13 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts).to.be.empty; page.go(quickstart); analytics.reportPageView(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); }); @@ -671,8 +704,10 @@ describe('Analytics', () => { // A sign-in's answer reaches the playground through the tab's session, so the page it returns to holds none back. it('inserts them at once on a page whose own link carries a state parameter', () => { const page = browser(`${quickstart}?state=CA`); + const analytics = new Analytics(withGtm(), listed); - new Analytics(withGtm(), listed).start(); + analytics.start(); + analytics.loadScripts(); expect(page.scripts.map((script) => script.src)).to.deep.equal([GTM_SCRIPT, SETUP, WIDGET]); }); @@ -684,9 +719,13 @@ describe('Analytics', () => { ] as const) { it(`reloads the page for a start with ${change}, as a config save under portal serve makes`, () => { const page = browser(quickstart); - new Analytics(none, listed).start(); + const first = new Analytics(none, listed); + first.start(); + first.loadScripts(); + const saved = new Analytics(none, [...next]); - new Analytics(none, [...next]).start(); + saved.start(); + saved.loadScripts(); expect(page.reloads()).to.equal(1); expect(page.scripts.map((script) => script.src)).to.deep.equal([SETUP, WIDGET]); @@ -712,7 +751,9 @@ describe('Analytics', () => { return append(script); }; - new Analytics(withGtm(), [{ src: 'https://cdn.example.com/widget.js' }]).start(); + const analytics = new Analytics(withGtm(), [{ src: 'https://cdn.example.com/widget.js' }]); + analytics.start(); + analytics.loadScripts(); expect(atEachInsert).to.deep.equal(['function', 'function']); @@ -837,6 +878,7 @@ describe('Analytics', () => { analytics.start(); analytics.reportPageView(); + analytics.loadScripts(); expect(page.window.apimatic).to.equal(locked); expect(page.scripts.map((script) => script.src)).to.deep.equal([