apollographql / apollographql/apollo-server

Different dists for CJS and ESM are causing both to be used, leading to TypeScript problems

Open
#7,625 17 comments 11 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
14k
Forks
2k
Avg merge
2d 14h
Merged PRs (30d)
2

Description

### Issue Description

`@apollo/server` provides different builds for ESM and CJS. It is great to see more ESM support, but the current approach means it suffers from the [Dual package hazard](https://nodejs.org/api/packages.html#dual-commonjses-module-packages) described in the node documentation.

To sum up the hazard: this approach makes it extremely likely that both the ESM and CJS versions will be loaded at the same time. Here is a simple example of how this can happen:

- Your project is written in ESM.
- Your project uses `@nestjs/apollo`. nestjs is written in commonJS and imports `@apollo/server`
- Your project includes a plugin for apollo, so you also import `@apollo/server`
- Your project will load the ESM version of apollo, and nest will load the CJS version. Meaning the plugin cannot be compatible with nest.

I strongly recommend doing everything you can to only ship a single build to node users by either:

- Dropping support for CJS altogether
- Or using the "ES module wrapper" approach. The first approach described here: https://nodejs.org/api/packages.html#dual-commonjses-module-packages. Approach 2 suggested by node does not work for TypeScript users. [Here is a real world example](https://github.com/sequelize/sequelize/blob/3f76bd42b4766d58c037e4785f5e7a573ba5b9e2/packages/core/package.json#L25) and [a test that makes sure the wrapper is kept in sync](https://github.com/sequelize/sequelize/blob/3f76bd42b4766d58c037e4785f5e7a573ba5b9e2/test/esm-named-exports.test.js)

I've provided a minimalist example of what sort of errors this causes below

### Link to Reproduction

https://codesandbox.io/p/sandbox/laughing-sun-85cmy8?file=%2Fsrc%2Findex.ts%3A1%2C1

### Reproduction Steps

See above

Contributor guide

Open the contributing guide

Research direction

Start with the linked CodeSandbox reproduction and the Node.js dual package hazard documentation to understand how the ESM and CJS builds are loaded together. Review the package distribution approach and verify completion by ensuring the reported TypeScript and compatibility problem no longer occurs while avoiding simultaneous ESM and CJS versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.