Skip to content

fix(teams): stop SmallTeam pills breaking hydration - #21013

Merged
ianmatson merged 2 commits into
masterfrom
fix/small-team-pill-hydration
Oct 9, 2026
Merged

ianmatson merged 2 commits into
masterfrom
fix/small-team-pill-hydration

Conversation

@ianmatson

@ianmatson ianmatson commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #20394.

On /careers, stacked team-name text covers the top of the "Who's hiring?" hero for about one second after the page loads. The cause is the SmallTeam pill. Its mini crest uses GatsbyImage, which always outputs <div> elements. The pill sits inside prose <p> text, and a <div> cannot go inside a <p>.

When the browser parses the server HTML, it closes the <p> early and splits the pill link. The pill has absolute top-0 left-0, so it moves out of its relative parent and draws at the top-left of the page content, on top of the hero. React then finds a DOM that does not agree with its tree. It throws error #418, then #423, and renders the whole root again on the client. That client render puts the pills back, so the fault shows only at load.

This PR draws the 20 px mini crest as a plain <img loading="lazy">. It uses the same src, srcSet, and sizes from the Gatsby image data. The pill looks the same, and the crests still load lazily. The crest variant does not change.

Why not keep GatsbyImage? It can stay valid inside a <p> only with three settings together: as="span", layout: FIXED, and placeholder: BLURRED. Each setting removes one <div> (the wrapper, the sizer, and the placeholder). That depends on plugin internals, and an upgrade could add a <div> again without any warning. At 20 px, the only real benefit of GatsbyImage is lazy loading, and the plain <img> keeps it. I also measured the WebP versions: at 128 px, which a 2× screen downloads, the WebP is 5,030 bytes and the PNG is 2,762 bytes.

SmallTeam is used in about 120 files, mostly inside paragraphs. So this change can also remove hydration errors on other pages. I did not check other pages one by one.

🔍 Reviewer's guide

Testing done

Check Command / method Result
Formatting prettier --check on the changed file, and the pre-commit hook (prettier and eslint) No changes needed
Types tsc --noEmit No errors in SmallTeam
Server HTML Dev server with DEV_SSR: true (local only, not committed). Loaded /careers with the Gatsby bundles blocked, in all four states Before: 2 pills outside their relative parent. After: 0
Hydration, dev Loaded /careers with JavaScript on, in all four states, and collected console errors and warnings Before: validateDOMNesting: <div> cannot appear as a descendant of <p>, "Hydration failed", and "the entire root will switch to client rendering". After: none of these
Console, new errors Compared the console set before and after No new messages. Messages on both sides: the header logo <svg> width "auto" error, one 404, a componentWillMount warning, and a Radix id attribute mismatch
Parser test Gave Chrome the old and new pill markup inside a <p> with page.setContent Before: 2 paragraphs and 4 links. After: 1 paragraph and 1 link
Lazy loading Test page in Chrome: a pill at the top and a pill 6,000 px down, then a scroll Top crests (visible and hidden copies) load at once. Lower crests load only after the scroll
Live site Loaded production /careers with several time zones and user agents 13 × #418, then #423, on every load. This agrees with the session recordings in the issue

Not tested: production build (pnpm build) and a Vercel preview, so I did not see the #418 count in production go to 0. In production, React does not throw for the Radix id attribute mismatch, but a preview must confirm this. The "Select a role" dead click from the issue is not part of this PR.

Screenshots

/careers server HTML, before hydration

These show the page that a visitor sees before React renders on the client. The "before" shots show the stacked pill above the hero.

State Before After
Light, narrow window (375 px)
Light, wide window (1440 px)
Dark, narrow window (375 px)
Dark, wide window (1440 px)

Team pill after hydration

The pill must look the same. "Before" is production, because the dev error overlay covers the pill in the local "before" state.

State Before After
Light, narrow window (375 px)
Light, wide window (1440 px)
Dark, narrow window (375 px)
Dark, wide window (1440 px)

What to look at

  1. src/components/SmallTeam/index.tsx: the plain <img> replaces GatsbyImage in every pill on the site. The pill loses the WebP <picture> source and the blur-up placeholder, but keeps lazy loading. At 20 px the WebP is not smaller, and the placeholder is not visible. If fallback is ever missing, the pill shows no crest, the same as when miniCrestImage is missing today.

GatsbyImage always outputs div elements (wrapper, sizer, placeholder).
SmallTeam pills sit inside prose paragraphs, so the HTML parser closed
the <p> early and split the link. The absolutely positioned pill then
escaped its relative parent and drew over the top of the content, e.g.
the /careers hero headline. React saw a DOM that did not match (#418)
and client-rendered the whole root (#423).

Refs #20394
@github-actions github-actions Bot added the website About the website (beyond just landing pages) label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Oct 09, 2026 02:49PM

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

10.09 MiB (+0.0 KiB / +0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 19.35 MiB (+0.1 KiB / +0.0%) report-only 2083
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1318.8 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 810.6 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs 481.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs 450.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs 385.8 KiB
./src/hooks/useCustomers.tsx + 59 modules 380.8 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 127 modules 310.3 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs 284.1 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs 275.7 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@ianmatson
ianmatson marked this pull request as ready for review October 9, 2026 14:36
@ianmatson
ianmatson merged commit 1ec06e1 into master Oct 9, 2026
24 of 25 checks passed
@ianmatson
ianmatson deleted the fix/small-team-pill-hydration branch October 9, 2026 14:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

website About the website (beyond just landing pages)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug Report: text overlaps the "Who's hiring?" hero headline on /careers at load

1 participant