feat: add Carbon Ads Top Bar and Sidebar placements by mcollina · Pull Request #9250 · nodejs/nodejs.org

mcollina · 2026-10-30T11:21:43Z

Description

Adds Carbon Ads, served through the OpenJS Foundation's Carbon project for Node.js, using two formats:

Top Bar (CWBI6KJY): full width, below the navigation, on the about, article, blog-post, blog-category, download and download-archive layouts.
Sidebar (CWBI6KJU): below the table of contents. It appears on about/article from xl (1280px) and on blog-post from ml (896px). Below those widths it is neither shown nor requested, as the format requires.

The homepage and the error/404 pages never render ad markup, reserve no space and make no ad requests. Layouts opt in explicitly (<WithNavBar ads />, <WithMetaBar ads="article" | "post" />), and ads are off by default. The fallback page layout has no ads.

Brian Edit Start

with Banner

Brian Edit End

Ads are rendered from Carbon's JSON API directly in the browser, without third-party scripts:

apps/site/util/carbonAds.ts: requests ads, validates the untrusted response (required fields, hex colours, HTTPS URLs; anything invalid means no ad), and measures viewability. The view beacon fires once, after at least 50% of the ad has been visible for one continuous second while the tab is visible.
apps/site/providers/carbonAdsProvider.tsx: tracks page views by locale and pathname. Each format is requested at most once per page view, so StrictMode, remounts, rerenders, theme changes and hash links never record extra impressions, and a revisited page gets a fresh ad.
apps/site/components/CarbonAds: renders both formats. While loading, the slot reserves space; when there is no ad (an empty response, an error or an ad blocker), the slot collapses.
MetaBar (ui-components) gains a generic optional footer slot, opt-in and with no ad-specific code.

Staging vs production

Every request includes ignore=yes, so impressions are not counted, unless the build sets NEXT_PUBLIC_CARBON_ADS_PRODUCTION=true. Local development and preview deployments are therefore non-counting by default. The variable is embedded at build time and must only be set for the production deployment. See docs/carbon-ads.md for the configuration and Carbon's launch sequence:

Carbon reviews a staging URL.
Production is enabled.
For seven days Carbon counts traffic but returns empty responses, so the slots render nothing.
Paid ads then start appearing in the same slots.

Learn and the API docs are separate applications and are not affected.

Validation

pnpm lint, lint:types (site and ui-components), Prettier and pnpm build pass.
Unit tests: site 247/247 and ui-components 45/45 pass. New coverage:
- validation of the response data
- fetch failure modes
- viewability timing: 49%, 999ms, threshold resets, hidden tab, cleanup
- StrictMode, remounts, A→B→A and locale changes
- stale responses after navigation
- Sidebar eligibility
- the MetaBar footer slot
A new e2e spec, tests/e2e/carbon-ads.spec.ts, uses mocked Carbon responses to check:
- no requests and no markup on the homepage
- one request per format per page view across client-side navigation
- no Sidebar request on narrow screens
A manual Playwright check against next start, with fixture responses using maximum-length creatives, passed all 238 checks:
- every layout at 375, 768, 895/897, 1279/1281 and 1600px
- localized homepages, loaded directly and after client-side navigation
- light and dark themes
- empty and blocked responses
- a short desktop viewport
- resizing across the breakpoints
- keyboard focus and horizontal overflow

Note: the e2e spec caught a React Compiler issue that unit tests (which run without the compiler) could not catch. The compiler hoisted the page-view Map/Set out of the useMemo, which shared them across navigations. The objects are now created through a function of the page-view key.

Reviewers might want to check:

The Sidebar styling, including the gradient fading into the image, against Carbon's reference CSS.
The 96px Top Bar reservation on narrow screens. It fits typical copy, but a maximum-length description is about 137–157px tall and causes a small layout shift.

Related Issues

None.

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run pnpm format to ensure the code follows the style guide.
I have run pnpm test to check if all tests are passing.
I have run pnpm build to check if the website builds without errors.
I've covered new added functionality with unit tests if necessary.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sfj4nGFRyF6F4tLo3KmVjH

vercel · 2026-10-30T11:21:47Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nodejs-org	Ready	Preview	Oct 31, 2026 12:31pm UTC

codecov · 2026-10-30T11:24:29Z

Codecov Report

❌ Patch coverage is 87.50000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.21%. Comparing base (53d777b) to head (c5fa893).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...ges/ui-components/src/Containers/MetaBar/index.tsx	60.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9250      +/-   ##
==========================================
+ Coverage   86.14%   86.21%   +0.06%     
==========================================
  Files          87       87              
  Lines        6164     6179      +15     
  Branches      369      370       +1     
==========================================
+ Hits         5310     5327      +17     
+ Misses        850      848       -2     
  Partials        4        4

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

ovflowd · 2026-10-30T11:25:34Z

Oh boi... here we go.

@mcollina could you add screenshots of how it looks when there are ads?

do we already have plans to deal with the potential negative PR and influx of issues that will come with the fact we are serving ads? 🙈

mcollina · 2026-10-30T11:32:42Z

These are the same ads mdn uses. I'll leave @rginn handle the public comms

github-actions · 2026-10-30T11:32:48Z

📦 Build Size Comparison

Summary

Metric	Value
Old Total First Load JS	7.21 MB
New Total First Load JS	7.23 MB
Delta	19.08 KB (+0.26%)

Changes

🔄 Modified Routes (4)

Route	Old First Load JS	New First Load JS	Delta
`/[locale]`	1.69 MB	1.70 MB	📈 4.77 KB (+0.28%)
`/[locale]/[...path]`	1.69 MB	1.70 MB	📈 4.77 KB (+0.28%)
`/[locale]/blog/[...path]`	1.69 MB	1.70 MB	📈 4.77 KB (+0.28%)
`/[locale]/download/archive/[version]`	1.69 MB	1.70 MB	📈 4.77 KB (+0.28%)

bmuenzenmeyer · 2026-10-30T12:05:57Z

personally, I'm opposed to:

we also use banners in that region to signify major events like security releases. we are now intentionally drawing eyeballs up there for multiple, competing needs.
the top bar interrupting the nav to content eyeline and using extremely contrasting color.
the logo on the ~~right~~left looks like too website headers loaded.

Important

Per content vs code, this is only my opinon.

bmuenzenmeyer · 2026-10-30T13:44:52Z

Learn and the API docs are separate applications and are not affected.

We've taken aims to make the three deployments look like a singular site, so I imagine we will have to extend this to doc-kit for at least learn, and perhaps API docs too.

doc-kit consumers from other projects may want this functionality anyway

MattIPv4 · 2026-10-30T14:01:17Z

👀 Two thoughts:

The downloads page is what I'd consider to be quite an important/sensitive page. Are we worried about this rendering above the actual download information / pushing that information down?
Are we concerned about the visuals of having a banner ad render below the nav while also having our own announcement banner render above the nav?

ovflowd · 2026-10-30T14:39:23Z

Learn and the API docs are separate applications and are not affected.

We've taken aims to make the three deployments look like a singular site, so I imagine we will have to extend this to doc-kit for at least learn, and perhaps API docs too.

doc-kit consumers from other projects may want this functionality anyway

Right, I'm talking to @avivkeller in person and we should make a @node-core/analytics package to put all analytics related things in there... Or maybe a component inside @node-core/ui-components like a Provider and a Component for Carbon and then the client/API keys etc get injected on each App.

ovflowd

Adding a formal block for now due to the technical/design open questions we need to figure out first.

To be clear, we are not against the addition and we will comply to it, but we oughta get this aligned as anything else here first :)

Thank you for submitting this, tho, @mcollina

mcollina · 2026-10-30T15:10:44Z

Can someone with better design skills take over on where to place those?
I literally throw this over the fence, and I'm not exactly the best person qualified for the job.

@bmuenzenmeyer @ovflowd wdyt about proposing something?

mcollina · 2026-10-30T15:13:00Z

👀 Two thoughts:

The downloads page is what I'd consider to be quite an important/sensitive page. Are we worried about this rendering above the actual download information / pushing that information down?

Yes, I think we can skip for this

Are we concerned about the visuals of having a banner ad render below the nav while also having our own announcement banner render above the nav?

I'm not the best person to lead a long collaborative UI design discussion, and it would be great if somebody else take over.

ovflowd · 2026-10-30T15:14:17Z

Can someone with better design skills take over on where to place those? I literally throw this over the fence, and I'm not exactly the best person qualified for the job.

@bmuenzenmeyer @ovflowd wdyt about proposing something?

Absolutely, don't worry, we'll take care of it :)

bmuenzenmeyer · 2026-10-30T15:36:54Z

The downloads page is what I'd consider to be quite an important/sensitive page. Are we worried about this rendering above the actual download information / pushing that information down?

Yes, I think we can skip for this

addressed via 7b4b748

bmuenzenmeyer · 2026-10-30T16:18:06Z

myself, @ovflowd and @avivkeller did an impromptu session

with potential security releases

as opposed to a potential future where we get this

cc @mcollina

MattIPv4 · 2026-10-30T16:24:07Z

with potential security releases

Very much a fan of this 👍

bmuenzenmeyer · 2026-10-30T16:54:52Z

Pushed the new topbar strategy to all in-scope layouts for further review.
Aligned the border radii with other banners of this type
Updated the docs

avivkeller · 2026-10-31T09:15:22Z

@avivkeller to be precise, you mean https://nodejs.org/docs/latest/api/ and any future doc-kit generated versions, correct?

I just post to clarify docs site as api docs

Correct, I mean the statically generated documentation we generate on every release.

ovflowd

SGTM with two final comments

avivkeller

Blocking to prevent accidental merges – @mcollina @rginn when should we actually merge this change and begin ads on the website?

Co-authored-by: Claudio Wunder <cwunder@gnome.org> Co-authored-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com> Co-authored-by: Matteo Collina <hello@matteocollina.com>

mcollina requested review from a team as code owners October 30, 2026 11:21

mcollina deployed to Storybook October 30, 2026 11:21 — with GitHub Actions

View deployment

vercel Bot deployed to Preview October 30, 2026 11:22

View deployment

github-code-quality Bot found potential problems Oct 30, 2026

View reviewed changes

Comment thread apps/site/components/CarbonAds/__tests__/index.test.jsx Fixed

Comment thread apps/site/components/CarbonAds/__tests__/index.test.jsx Fixed

This comment was marked as outdated.

Sign in to view

avivkeller added the web-agenda label Oct 30, 2026

ovflowd requested changes Oct 30, 2026

View reviewed changes

bmuenzenmeyer deployed to Storybook October 30, 2026 15:35 — with GitHub Actions Active

vercel Bot deployed to Preview October 30, 2026 15:36

View deployment

vercel Bot deployed to Preview October 30, 2026 16:54

View deployment

ovflowd reviewed Oct 30, 2026

View reviewed changes

Comment thread apps/site/components/CarbonAds/index.tsx Resolved

ovflowd reviewed Oct 30, 2026

View reviewed changes

Comment thread apps/site/components/CarbonAds/index.tsx Resolved

ovflowd reviewed Oct 30, 2026

View reviewed changes

Comment thread apps/site/components/MetaBar.tsx Resolved

bmuenzenmeyer deployed to Storybook October 31, 2026 06:25 — with GitHub Actions Active

vercel Bot deployed to Preview October 31, 2026 06:26

View deployment

github-code-quality Bot found potential problems Oct 31, 2026

View reviewed changes

bmuenzenmeyer deployed to Storybook October 31, 2026 06:48 — with GitHub Actions Active

vercel Bot deployed to Preview October 31, 2026 06:49

View deployment

bmuenzenmeyer deployed to Storybook October 31, 2026 06:56 — with GitHub Actions Active

vercel Bot deployed to Preview October 31, 2026 06:56

View deployment

avivkeller force-pushed the feat/carbon-ads branch from ad77c54 to 66e57c3 Compare October 31, 2026 11:11

avivkeller deployed to Storybook October 31, 2026 11:11 — with GitHub Actions

View deployment

vercel Bot deployed to Preview October 31, 2026 11:11

View deployment

avivkeller deployed to Storybook October 31, 2026 11:35 — with GitHub Actions

View deployment

vercel Bot deployed to Preview October 31, 2026 11:36

View deployment

ovflowd reviewed Oct 31, 2026

View reviewed changes

Comment thread apps/site/hooks/useCarbonAd.ts Resolved

ovflowd reviewed Oct 31, 2026

View reviewed changes

Comment thread apps/site/hooks/useCarbonAd.ts Resolved

ovflowd reviewed Oct 31, 2026

View reviewed changes

Comment thread apps/site/hooks/useCarbonAd.ts Resolved

ovflowd approved these changes Oct 31, 2026

View reviewed changes

avivkeller requested changes Oct 31, 2026

View reviewed changes

avivkeller deployed to Storybook October 31, 2026 12:17 — with GitHub Actions Active

vercel Bot deployed to Preview October 31, 2026 12:18

View deployment

chore: carbon ads

eae362a

Co-authored-by: Claudio Wunder <cwunder@gnome.org> Co-authored-by: Brian Muenzenmeyer <brian.muenzenmeyer@gmail.com> Co-authored-by: Matteo Collina <hello@matteocollina.com>

avivkeller force-pushed the feat/carbon-ads branch from de67bc8 to eae362a Compare October 31, 2026 12:18

avivkeller deployed to Storybook October 31, 2026 12:19 — with GitHub Actions

View deployment

vercel Bot deployed to Preview October 31, 2026 12:19

View deployment

fixup!

c5fa893

avivkeller deployed to Storybook October 31, 2026 12:31 — with GitHub Actions Active

vercel Bot deployed to Preview October 31, 2026 12:31

View deployment

Conversation

mcollina commented Oct 30, 2026 • edited by bmuenzenmeyer Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Staging vs production

Validation

Related Issues

Check List

Uh oh!

vercel Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ovflowd commented Oct 30, 2026

Uh oh!

mcollina commented Oct 30, 2026

Uh oh!

github-actions Bot commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Build Size Comparison

Summary

Changes

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

bmuenzenmeyer commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

bmuenzenmeyer commented Oct 30, 2026

Uh oh!

MattIPv4 commented Oct 30, 2026

Uh oh!

ovflowd commented Oct 30, 2026

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

mcollina commented Oct 30, 2026

Uh oh!

mcollina commented Oct 30, 2026

Uh oh!

ovflowd commented Oct 30, 2026

Uh oh!

bmuenzenmeyer commented Oct 30, 2026

Uh oh!

bmuenzenmeyer commented Oct 30, 2026

Uh oh!

MattIPv4 commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bmuenzenmeyer commented Oct 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller commented Oct 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

mcollina commented Oct 30, 2026 •

edited by bmuenzenmeyer

Loading

vercel Bot commented Oct 30, 2026 •

edited

Loading

codecov Bot commented Oct 30, 2026 •

edited

Loading

github-actions Bot commented Oct 30, 2026 •

edited

Loading

bmuenzenmeyer commented Oct 30, 2026 •

edited

Loading

MattIPv4 commented Oct 30, 2026 •

edited

Loading