Skip to content

fix(portal): load custom scripts once the page is ready, so they can change it - #481

Merged
sohail2721 merged 1 commit into
devfrom
sohail/scripts-after-hydration
Nov 19, 2026
Merged

sohail2721 merged 1 commit into
devfrom
sohail/scripts-after-hydration

Conversation

@sohail2721

@sohail2721 sohail2721 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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.scripts as 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() and reportPageView() insert only the Google tags. A new loadScripts() inserts the listed scripts, each once, as before.
  • components/listed-scripts.tsx: a new component that renders nothing and calls analytics.loadScripts() from its effect.
  • routes/$.tsx: one <Suspense> now holds every kind of page's content, together with ListedScripts. Before, only a Markdown page's content had one.
    • React hydrates the root first, then each Suspense boundary in a later pass, and the content's boundary comes last. So the effect runs only once the whole page is hydrated.
    • A boundary of its own for ListedScripts wasn'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: renders ListedScripts too.

What changes for a script

  • Later start: a script runs once the page is hydrated. On a guide page that is about 205 ms after navigation instead of about 140 ms, and about 1.3 s instead of about 0.8 s with the CPU slowed six times.
  • Consent tools: with googleConsentMode set, the Google tags still start as denied. A consent tool listed in portal.scripts runs 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.
  • Moving between pages: an element added to the header or sidebar stays as the reader moves between pages. One added inside a page's content stays on the next guide page and is gone on an API reference page.

Tests

  • test/portal-template/analytics.test.ts: the listed-script tests call loadScripts() after start(). A new test pins that neither a start nor a page view inserts a listed script, and that loadScripts() inserts all of them.
  • That file and test/portal-template/event-feed.test.ts: 109 passing.
  • APIMATIC_E2E=1: test/e2e/portal-build.test.ts 81 passing, test/e2e/portal-serve.test.ts 6 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.

  • The #2357 repro: a listed file adds an element to the header, the sidebar, the article and <body> when it runs.
  • The checks from feat(portal): load custom scripts from portal.scripts #477, run again:
    • Listed scripts run in list order, once per page load, and not again on client-side moves. An address listed twice loads once.
    • Under /docs, files load from /docs/js/….
    • subscribe() replays the first page view to a listed script, delivers live events, freezes them, unsubscribes, and throws a TypeError for a non-function.
    • /oauth/callback loads no script and no tag.
    • --no-analytics leaves out analytics and marketing scripts and sends no events.
    • A script the host already put in <head> downloads once, and the host's own object at window.apimatic is kept.
    • Under portal serve, four config saves each reload the page once with exactly the new list.
    • No uncaught errors. The not-found page still logs the deliberate "Falling back to the not-found page" message from routes/$.tsx.

Not covered

  • The API playground: it hydrates in Suspense boundaries of its own, which can finish after the scripts load. A script that changes the playground itself wasn't tried.
  • Google Tag Manager: its tags still start immediately, so a Custom HTML tag that changes the page early isn't covered by this change.

Docs

apimatic/apimatic-docs#887 (da17d7aa) changes Add Custom Scripts:

  • The portal adds the scripts once the page is ready.
  • What happens to an element a script adds as the reader moves between pages.
  • A script that never answers can delay the load event, rather than always delaying it.

🤖 Generated with Claude Code

…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>
@sonarqubecloud

Copy link
Copy Markdown

@sohail2721
sohail2721 merged commit f7b9f0d into dev Nov 19, 2026
18 checks passed
@sohail2721 sohail2721 mentioned this pull request Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 2.3.0-beta.2 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants