spike(GMT-1715): tsdown build — go/no-go criterion #4

[dreamwasp]

Overview

Spike, not for merge. Closes go/no-go criterion #4 for the 1.0 reboot: can
tsdown replace tsc --emitDeclarationOnly + babel ./src --out-dir ./dist, producing
the reboot's decided output shape (bundled per entry + a strict exports map)?

Yes. Written up in TSDOWN-SPIKE.md at the repo root.

Built three real packages — variance (pure TS), gamut-styles (16 .tsx, 20 Emotion
imports) and gamut (426 files, 106 Emotion styled) — each producing bundled ESM

• CJS and .d.mts/.d.cts, 4–7x faster than the current tsc + babel pair
  (gamut: ~17.3s → 2.3s).

The load-bearing result: no Babel bridge is needed

The concern was that a Phase 1 tsdown migration would need a scoped
@rolldown/plugin-babel bridge for @emotion/babel-plugin, which Phase 2 would then
delete. It doesn't — tsdown built both Emotion-heavy packages with no Babel at all.

Consequence: the build migration is independent of the styling work and can land
first. That reversed the planned phase ordering.

Second commit: the declarations claim, corrected

8c2ce2b03 corrects the first commit. Bundled declarations don't compose, so the shape
is a hybrid: JS from tsdown, declarations from tsc. The part worth keeping is
why it works rather than that it works —
rolldown-plugin-dts#174
(directives leaking into .d.ts) cannot occur in a hybrid build, because
declarations carry no statements and there is nowhere to put a directive prologue.
Structurally unreachable rather than luckily avoided, so nobody re-verifies it after a
version bump. One exports map serves both output shapes.

Output contract validated end to end

• Real exports maps resolved through the package name
• The mono deep-import preserved as a genuine subpath
  (@codecademy/gamut-styles/AssetProvider → createFontLinks)
• The old dist/AssetProvider path correctly blocked with
  ERR_PACKAGE_PATH_NOT_EXPORTED

Two findings worth carrying regardless of this spike's fate

1. Today's Babel output is not valid Node ESM — extensionless specifiers, 10 in
   variance alone. It only works because consumers bundle.
2. Latent type-only re-export debt that Babel hides and a bundler rejects — 6 names
   across 2 files, fixed here. Neither isolatedModules nor verbatimModuleSyntax is
   enabled anywhere, which is why it accumulated.

⚠️ Known error in TSDOWN-SPIKE.md, not yet corrected in the file

TSDOWN-SPIKE.md:33-34 says @emotion/babel-plugin is "DX, not correctness". That is
wrong. The three configured options (sourceMap, autoLabel, labelFormat) are
cosmetic, but the plugin also stamps target unconditionally, outside any option —
verified in the plugin's own dist, where target is pushed with no guard while label
two lines later is gated on autoLabel !== 'never'.

target is load-bearing for component selectors (${Component} in selector
position). Without it, @emotion/styled returns NO_COMPONENT_SELECTOR, which
@emotion/serialize throws on in development and silently renders as .undefined in
production. Real exposure: 1 site here
(packages/gamut/src/BarChart/BarRow/elements.tsx:64) and 22 confirmed consumer sites.

The conclusion survives — no Babel bridge is needed — but the supporting sentence
doesn't, and the removal work item is larger than "readable class names".

PR Checklist

• Related to designs: n/a — build tooling
• Related to JIRA ticket: GMT-1715
• Version plan added/updated (or not needed) — not needed, spike
• I have run this code to verify it works
• This PR includes unit tests for the code change — no; the spike's assertions are
  the build itself plus the resolution checks in TSDOWN-SPIKE.md
• This PR includes testing instructions
• The alpha package of this PR is passing end-to-end tests in all relevant
  Codecademy repositories — no. See limitations.

Testing Instructions

# per-package builds
yarn workspace @codecademy/variance     tsdown
yarn workspace @codecademy/gamut-styles tsdown
yarn workspace @codecademy/gamut        tsdown

# then verify the exports map actually gates resolution
node -e "import('@codecademy/gamut-styles/AssetProvider').then(m => console.log(Object.keys(m)))"
node -e "import('@codecademy/gamut-styles/dist/AssetProvider').catch(e => console.log(e.code))"
#   expect: createFontLinks present, then ERR_PACKAGE_PATH_NOT_EXPORTED

Compare timings against yarn build on main for the same packages.

Limitations — please read before drawing conclusions

• Bare tsc invocation, and no consumer build has run anywhere. Not mono's Next
  build, not platform's Rspack, not front's Webpack.
• The hybrid was proven on gamut-styles, whose declaration layout happens to line up
  with its entry names. That is a property of that package, not of the approach.
  packages/gamut (426 files) is untested and is where the entry list stops being
  obvious.
• The exports map here is not yet designed around the inventory of ~66 deep
  dist/ imports across mono (19) and platform (47). Two of our own spikes have already
  broken on it accidentally.

PR Links and Envs

Repository	PR Link
Mono	none — no consumer build attempted
Monolith	none — no consumer build attempted

Related reboot spikes: #3402 (styling proof of concept) · #3405 (Panda under the hood) ·
#3406 (engine-neutral DTCG tokens).

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 8c2ce2b

Command	Status	Duration	Result
nx run-many --target=build --all	❌ Failed	13s	View ↗

💡 Dealing with memory or CPU issues? See memory and CPU details with the resource usage add-on ↗.

---

☁️ Nx Cloud last updated this comment at 2026-08-11 14:02:35 UTC

[codecov]

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.