diff --git a/portal-template/src/components/listed-scripts.tsx b/portal-template/src/components/listed-scripts.tsx
new file mode 100644
index 00000000..d662e771
--- /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 3eba7d78..e62de595 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 148d65e5..56a4cd4c 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 b884d880..1e85470f 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 c44d685d..876bd3ec 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([