fix(portal): bundle the Geist fonts instead of loading them from Google Fonts

[saeedjamshaid]

A generated portal was slow to show anything on its first load. It waited on the Google Fonts stylesheet. The portal's own files all arrived within about 60 ms, but nothing appeared until fonts.googleapis.com answered. The portal now ships Geist and Geist Mono with its other assets, so a page makes no requests to other domains.

Why

The stylesheet blocked the first paint and hydration. __root.tsx linked the Geist stylesheet from Google Fonts. A stylesheet in <head> blocks rendering, and module scripts wait for it before running. So every page stayed blank and inert until a connection to Google was set up and the CSS came back. From here that took about 1.1 s on a warm connection and 3.4 s on a cold first attempt, most of it connection and TLS setup. On a later visit the connection and CSS are cached, which is why only the first load felt slow.

Taking the tag out of the HTML is not enough. TanStack's HeadContent renders the route's head() links again after hydration. React 19 then holds its updates until a stylesheet it manages has loaded. With the tag stripped from the HTML only, the page painted early, but code highlighting still waited about 2.5 s for the stylesheet to arrive.

What changes

• Fonts are bundled. @fontsource-variable/geist and @fontsource-variable/geist-mono 5.3.0 are new CLI dependencies. app.css imports them, and Vite copies the woff2 files into assets/. It's the same variable font as before (weights 100–900), and unicode-range means only the subsets a page uses are downloaded. The Google links are removed from __root.tsx.
• The font packages are copied into the build project, not linked. Tailwind rewrites the url()s in an imported stylesheet relative to the project. A linked package resolves to the CLI's install, so on Windows, with the project and the CLI on different drives, the rewritten path (../../C:/...) can't resolve. Every font would 404, and the published CSS would carry the install path. Copied, the files sit inside the project, and portal serve loads them with no extra Vite setting. portal-project-service.ts now keeps COPIED_DEPENDENCIES and LINKED_DEPENDENCIES as separate lists, and TEMPLATE_DEPENDENCIES is the two together.
• The font-sans and font-mono classes get Geist too. The theme used to set only Tailwind's page defaults, so everything Fumadocs styles with font-mono stayed in the system font. That covers the method badges, type tables, table of contents, search dialog and playground output: 33 elements on an operation page. --font-sans and --font-mono are set now, and the page defaults derive from them.
• NOTICE credits Geist under the SIL Open Font License 1.1, since the portal now redistributes the font files. Each woff2 file also carries the copyright notice and the licence URL in its own metadata, which the OFL FAQ (1.10) says is legally sufficient, so the published portal needs no separate licence file.

This also removes a third-party request from every published portal. That helps readers where Google is blocked, and removes a request that is a known GDPR complaint in the EU.

Verification

Measured in headless Chrome over the DevTools protocol against the test-source portal from portal generate, served locally with gzip and the browser cache disabled:

	Before	After
API page, first paint	1,244 ms	108 ms
API page, interactive	1,263 ms	157 ms
API page, first paint, throttled 4G	1,292 ms	324 ms
Home page, first paint, throttled 4G	1,560 ms	268 ms
Layout shift (CLS) from the font swap, API page	0.0002	0.0002

• The generated output has no Google URLs and serves both fonts from /assets/. In the browser, body text, code and font-mono elements render in Geist and Geist Mono.
• Under portal serve both font files return 200 from inside the build project.
• A new unit test checks that the font packages are real folders inside the project. It fails when they are linked. The e2e font test checks that both Geist files are bundled and that the theme variables are set.
• A packaging test scans every linked package and fails if any of its stylesheets has a relative url(), so a future package like the fonts can't be linked by mistake. Data URIs, absolute URLs and root-relative paths are ignored, since they resolve anywhere. None of the 18 linked packages has one today. I confirmed the test fails, naming both packages, when the fonts are moved to the linked list. A second test holds the copied list to packages that need the copy (they have a relative url()) and can take it (no dependencies of their own, which pnpm keeps beside a package rather than inside it). It fails if fumadocs-ui is added.
• The swap from the fallback font to Geist moves almost nothing. CLS is 0.0002 on an operation page (Google's "good" threshold is 0.1) and 0 on a guide page, the same as with Google Fonts. A build with the font files removed shows 0, so the swap accounts for all of it. Only the glyphs change, not the layout.
• pnpm test passes (1,134 tests, lint clean), and so does the end-to-end build suite run with APIMATIC_E2E=1 (33 tests).
• I couldn't run a real cross-drive build, because this machine has only one drive and the Windows CI runner keeps everything on D:. That's why the packaging test above checks the condition directly.

Left as is

• No font preload. Measured over HTTP/2, which is what most hosts serve. Preloading only the latin Geist file brings it in sooner: about 390 ms instead of 510 ms on fast 4G, and 1,650 ms instead of 2,160 ms on slow 4G. But first paint comes 65–150 ms later, because the font competes with the render-blocking stylesheet, and on slow 4G the text is still redrawn about 300 ms after it first appears. Since the swap moves nothing (CLS above), first-paint time is the better thing to keep. Over HTTP/1.1 a preload looked worse, because of the per-host connection limit, so that earlier result doesn't carry over.
• Real italics. As with the old Google URL, only the upright font loads, so italic text is a slanted copy of it. Both Fontsource packages ship wght-italic.css, and the files are already in the build project. Importing it would change how every <em> looks, so it's a follow-up.
• portal serve is still slow on its first page load: 2.5–3.6 s, then about 1 s. That's the Vite dev server preparing code on the first request, not the fonts, and it needs its own change.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀