Review Node.js package exports before outsourcing an ESM migration

Pack first; debate syntax second

An ESM migration can pass inside a monorepo and fail after publication. Workspace aliases, TypeScript paths, and test transforms often bypass package.json. Pack the current and candidate releases, list their files, and install each tarball in clean fixture projects. Exercise a small real operation instead of stopping after import. This exposes missing declarations, unpublished build output, executable permissions, and source imports that worked only because the package lived beside its consumer.

Create separate fixtures for a CommonJS service, ESM service, TypeScript NodeNext consumer, supported bundler, and command-line entry if one exists. Pin Node, package manager, compiler, and bundler versions in the evidence. A broad statement that “ESM works” expires as soon as a tool changes its resolution default. The support matrix should reflect actual maintained consumers rather than every theoretical combination.

Existing import strings reveal the public contract

Search maintained consumers for the package name. Collect root imports, documented feature subpaths, command names, self-references, and private files callers reached because no exports boundary existed. Classify them with the package owner. A supported subpath may remain; a private path may receive a migration or deliberate error. The exports map must not make that product decision silently. Test one intentionally blocked path and retain its clear failure as evidence.

Include dynamic import and require.resolve where consumers use them. Check default and named exports, extension rules, JSON loading, and top-level await against supported versions. A test suite that imports source modules directly does not cover this contract. Fixture projects should have no path aliases back to the repository and should install only the tarball and the dependencies a real consumer declares.

Two loaders can create two copies of one supposed singleton

When import and require resolve to separate builds, a stateful library can expose two registries, caches, symbols, clients, or error classes. Load both conditions in the same fixture. Compare identity, register a plugin through one, and observe it through the other. Ordinary function calls may pass while instanceof checks or plugin lookup fails. This is the dual-package hazard in a form a reviewer can see.

Dual output is not automatically the safest promise. It expands the build and test matrix. If remaining CommonJS callers can migrate, an ESM-only major release may be easier to maintain. If both formats remain supported, document how state is shared or why the package is stateless. The programmer provides the experiment; maintainers decide the compatibility promise and semantic version.

Resolve declarations and runtime code as a pair

Ask TypeScript to trace resolution for every fixture and compare the declaration target with the JavaScript that Node or the bundler loads. Runtime success with declarations from another entry can advertise functions the loaded code does not implement. Trigger one intentional error from each entry and inspect source maps and stack paths. Production stacks pointing at nonexistent build-machine files make incident diagnosis harder even when behavior is otherwise correct.

The handoff should include the specifier inventory, packed file lists and checksums, fixture repositories, commands, runtime results, type traces, identity test, blocked-path result, source-stack example, consumer migration notes, and recommended version boundary. Registry credentials and publication stay with maintainers. Review the exact packed artifact again in release automation, because rebuilding after approval can change the files that were tested.

Probe the resolution edges consumers actually depend on

Create a fixture for each supported Node line and run it outside the monorepo with an empty package-manager cache. Import the root, every documented subpath, and one explicitly private path. Execute a representative function, inspect the resolved filename, and capture whether the same operation works through require where that promise exists. Add a consumer that bundles for a server target and another that runs TypeScript without a build step only if those are maintained use cases. Test installation under a strict package manager so undeclared dependencies cannot leak from a workspace root. Compare the candidate tarball to the current release for file modes, shebangs, declaration maps, source maps, license files, and package metadata. If an export uses conditions, enumerate which condition each fixture selected. This catches a browser condition accidentally chosen for server-side rendering or a development file published without its production peer. A compatibility table should cite commands and exit status, not just checkmarks copied from the package's own suite.

Treat errors as part of the API surface. Trigger a validation error and a custom class through each entry, serialize it if consumers do that, and compare stack frames. Load a plugin through one module system and the host through the other. Test whether symbols, class identity, and global registration cross that boundary. Run the CLI from a directory whose name contains spaces and from a read-only working directory if the tool claims not to write there. Confirm optional peer dependency failures name the missing peer instead of producing an unrelated module error. Before recommending a release, search maintained repositories and documentation for deep imports that the new exports map blocks; attach owners and migration paths for each live use. The final review must distinguish a packaging defect from a deliberate compatibility break. Only maintainers choose the supported engines, module formats, and release number. The outsourced programmer can make that decision inexpensive by supplying packed artifacts, isolated consumers, exact resolution traces, and a rollback package whose checksum is known.

One final control should install the candidate beside a dependency that still expects the old package range. Inspect whether the package manager deduplicates them or keeps two copies, and whether shared objects cross that version boundary. Exercise package self-references from compiled output and confirm development source files are not required at runtime. Run npm pack or the chosen publisher's dry run from a clean checkout, then compare its checksum with the artifact used in fixtures. Document every intentional export, its declaration file, module format, minimum runtime, and owning test. This closes the gap between a source migration and a releasable compatibility contract.

Buyer questions

Questions about planning the role