Repository navigation
fix(portal): load custom scripts once the page is ready, so they can change it - #481
Merged
Merged
Conversation
…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 <body> 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 <noreply@anthropic.com>
sohail2721
requested review from
Shield-Jaguar and
saeedjamshaid
as code owners
November 19, 2026 08:09
|
mehnoorsiddiqui
approved these changes
Nov 19, 2026
Merged
Contributor
|
🎉 This PR is included in version 2.3.0-beta.2 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



Fixes the bug in the QA report apimatic/apimatic-io#2357. When a custom script added an element to the portal's header or to a page, the element was lost and the whole page was rebuilt.
Why
The portal inserted the scripts listed in
portal.scriptsas soon as its own code started, before React had hydrated the prerendered page. A script that added an element inside the page made hydration fail with React error #418. React then threw the whole prerendered page away and built it again in the browser, without the element. An element added to<body>survived, because React skips unknown nodes there.The problem is in the portal's own code, not in Fumadocs. Our loader decided when the scripts ran, and any element React renders breaks the same way, not only the Fumadocs header.
The change
The Google tags and the consent default still start immediately. The listed scripts now wait until React has hydrated the page.
analytics.ts:start()andreportPageView()insert only the Google tags. A newloadScripts()inserts the listed scripts, each once, as before.components/listed-scripts.tsx: a new component that renders nothing and callsanalytics.loadScripts()from its effect.routes/$.tsx: one<Suspense>now holds every kind of page's content, together withListedScripts. Before, only a Markdown page's content had one.ListedScriptswasn't enough. It finished first whenever the content was still waiting for its chunk, and 2 runs in 5 still failed.components/not-found.tsx: rendersListedScriptstoo.What changes for a script
googleConsentModeset, the Google tags still start as denied. A consent tool listed inportal.scriptsruns later by the same amount. On a slow device, a returning reader's first hit can go out as denied before the tool reports their answer, because the consent default waits 500 ms for it.Tests
test/portal-template/analytics.test.ts: the listed-script tests callloadScripts()afterstart(). A new test pins that neither a start nor a page view inserts a listed script, and thatloadScripts()inserts all of them.test/portal-template/event-feed.test.ts: 109 passing.APIMATIC_E2E=1:test/e2e/portal-build.test.ts81 passing,test/e2e/portal-serve.test.ts6 passing.Checked in a browser
All in headless Chrome, on portals built from this branch and served the way a static host serves them, and under
portal serve.<body>when it runs.<body>was replaced.portal servetoo./docs, files load from/docs/js/….subscribe()replays the first page view to a listed script, delivers live events, freezes them, unsubscribes, and throws aTypeErrorfor a non-function./oauth/callbackloads no script and no tag.--no-analyticsleaves outanalyticsandmarketingscripts and sends no events.<head>downloads once, and the host's own object atwindow.apimaticis kept.portal serve, four config saves each reload the page once with exactly the new list.routes/$.tsx.Not covered
Docs
apimatic/apimatic-docs#887 (
da17d7aa) changes Add Custom Scripts:loadevent, rather than always delaying it.🤖 Generated with Claude Code