ESM migration: convert lib batch 3 (printing and ui)

[eventualbuddha]

Overview

Library batch 3: printing and ui — the two links that had to come next, and the ones carrying the styled-components work. printing was the only library convertible at all (everything else was still blocked), and converting it unblocks ui, which in turn unblocks backend, ballot-encoder, fujitsu-thermal-printer and monorepo-utils for the next batch.

Three commits:

1. convert printing to ESM
2. normalize the styled-components default import in ui — 115 modules, a no-op for the current CommonJS build, landed separately so the mechanical churn is reviewable on its own and every commit is green.
3. convert ui to ESM — the codemod (1385 specifiers across 406 files) plus the manual work below.

libs/ui is the largest package in the repo at 476 TypeScript files, and unlike the frontend libraries it is on node resolution, because its output is loaded by node — backends render reports and ballots through it. That is what makes the interop work below necessary rather than cosmetic.

Reviewer's main focus

1. styled-components (commit 2). v5 ships CommonJS only, so under node's ESM interop import styled from 'styled-components' evaluates to module.exports — styled.div is undefined and every template literal throws at import time. Vitest and Vite hand back styled itself instead, so a fix written for one loader breaks the other. src/styled.ts accepts either shape; its type comes from the package's own StyledInterface rather than typeof styledDefault.default, because CommonJS and ESM type resolution disagree about what a default import of a CommonJS module is and this file has to type-check on both sides of the flip.

2. Three more dependencies with the same disagreement, each handled where it is used, and each caught a different way:

dependency	symptom	caught by
qrcode.react	import { QRCodeSVG } type-checks but fails to load — node cannot see the package's named exports; only the namespace's default has them, and Vite/vitest are the reverse	importing the built output under node
i18next	one types entry for both builds, so TS models the default as module.exports though node resolves the ESM build	tsc
@testing-library/user-event v13	CommonJS default import; affects 58 test files	tsc

3. ui's build configuration. i18next-parser.config.js becomes ESM rather than .cjs — i18next-parser looks for .js/.mjs/.json/.ts/.yaml (never .cjs) and loads it with import(). This one is load-bearing: build:app-strings-catalog runs inside build:self, so getting it wrong fails every build of ui and therefore of the repo. The existing comment explaining why the config is JavaScript rather than TypeScript still applies and now records the ESM part too.

4. The dev CLIs (three in printing, two in ui) import compiled output instead of installing esbuild-runner, which is a CommonJS require hook that can neither load ESM sources nor resolve the .js specifiers those sources now use. Four of them ran TypeScript that lived in scripts/, which the build does not compile, so there was nothing to import; those modules moved under src/ with a matching narrow coverage.exclude — they sat outside src/ before and so were never counted, and the two ui ones write back into src/, which is called out where the paths are resolved.

Also worth knowing: two specifier fixes the codemod cannot make. ./normalize.css is really normalize.css.ts, and the codemod skips anything ending in .css assuming it is a stylesheet. @testing-library/jest-dom/matchers needs its .js because that package has no exports map, so node16 resolves the subpath as a file path.

Demo Video or Screenshot

N/A — module-system change, no user-facing behavior change.

Testing Plan

Per package, locally:

	printing	ui
tsc --build	clean	clean
eslint / stylelint	clean	clean, incl. the app-strings-catalog check
vitest run	74/74, coverage 100%/99%	939 passed / 2 skipped over 168 files, coverage debt unchanged from baseline
built output under plain node	imports	all 255 modules import
CLIs	all three print usage; generate-m404n-ppd reproduces the committed PPD byte for byte	both run; generate-font-awesome-styles and the strings catalog regenerate identically

The whole-build/ import sweep is the check that matters most here, and it is new in this batch. The unit tests run under vitest, which resolves modules the way Vite does — the opposite side of every interop question in this PR — so they cannot see a node-only load failure. Sweeping all 255 built modules under plain node is what caught qrcode.react and the require.resolve, neither of which tsc or vitest flags.

Repo-wide on this branch: type-check passes for every dependent of both packages, and script/validate-monorepo is clean. CI covers the rest, including the frontend builds (Vite consuming ESM ui) and the integration tests that render through printing and ui inside real backends.

Checklist

• I have prefixed my PR title with "VxDesign: ", "VxPollBook: ", or "HWTA: " if my change is specific to one of those products.
• I have added logging where appropriate for any new user actions.
• I have added the "user-facing-change" label to this PR, if relevant, to automate an announcement in #machine-product-updates.

🤖 Generated with Claude Code

[eventualbuddha]

Parking this in draft — all 7 app-backend test suites fail, and the cause is test infrastructure rather than the libraries themselves. Recording the diagnosis so far.

Symptom. configureElectionPackageFromUsb runs the real election-package authentication and dies on Missing required VX_MACHINE_TYPE env var, because vi.mock("@votingworks/utils") — which the tests use to enable SKIP_ELECTION_PACKAGE_AUTHENTICATION — no longer reaches libs/backend.

Evidence (reproduces locally, so no CI round-trips needed):

• Instrumenting the decision point in libs/backend/src/election_package/election_package_io.ts shows it holding the real compiled isFeatureFlagEnabled, while a probe in the test file shows the mock. So there are two instances of @votingworks/utils in one test run.
• Checking out the commit before the ui flip (with printing already ESM) and rebuilding, the same probe shows libs/backend holding the mock. So converting ui is what splits the instances.

Fixes tried and ruled out, all at the test-config layer:

1. Aliasing @votingworks/utils to source — utils then loads from source, still unmocked.
2. Aliasing @votingworks/printing to source — no change.
3. server.deps.inline: [/@votingworks\//] — no change.

That the config layer cannot fix it suggests the problem is module-system consistency: libs/backend is CommonJS and now sits between ESM (ui, printing) and CommonJS (utils), and vitest cannot keep one instance across that boundary.

Worth stressing: this is test-harness breakage, not product breakage. The converted libraries are sound — all 255 built ui modules import under plain node, a mark-frontend Vite build succeeds, and all 13 dependents type-check.

Next step is probably to extend this PR to convert libs/backend as well and re-measure, and if that is not enough, to accept that the remaining spine (backend, utils, types, basics, …) has to convert in one PR rather than in waves — partial conversion is what creates the mixed graph.

[eventualbuddha]

Resolved — pushed as c106152a8d. Root cause was load ordering, not duplicate modules, and the fix touches no library code.

Tagging the module and logging from both sides showed one instance with two views:

backend sees utils instance: build:3ve7d | mocked? false
test file        utils    = build:3ve7d | mocked? true

Each test/setupTests.ts imported @votingworks/printing at module scope for one cleanupCachedBrowser() call. Setup files run before the test file, so before any vi.mock. As CommonJS printing was externalized and never entered vitest's module runner; as ESM it is processed by the runner, so importing it instantiates part of the graph pre-mock and those modules keep real bindings.

Fix: load printing inside the hook with vi.importActual (same instance when nothing is mocked, so cleanup still targets the browser the tests created), plus one narrowed node:fs stub in admin-backend's multi_station_config.test.ts, which replaced node:fs wholesale and so starved printing's import-time config read.

Measured on admin-backend, the hardest case: eager import → 31 tests failing; await import → 462 pass, 1 suite failing; vi.importActual + narrowed stub → 44/44 files, 462/462.

Two options ruled out with measurements rather than argument:

• Aliasing internal packages to source cannot fix this — aliases address module identity, this is timing. Aliasing utils, aliasing printing, and server.deps.inline: [/@votingworks\//] all left the mock unapplied.
• Making printing's config load lazy would have removed the hazard at its root, but SUPPORTED_PRINTER_CONFIGS feeds three exported consts with 168 usages across 45 files.

Follow-up worth considering: those same setup files also import fixtures, image-utils and test-utils at module scope, so each will reintroduce this when its batch converts. An eslint-plugin-vx rule banning module-scope @votingworks/* imports in **/setupTests.ts would catch it at authoring time.