enable conditional exports

cspell.yml

@@ -66,6 +66,7 @@ words:
 
   # TODO: contribute upstream
   - deno
+  - denoland
   - hashbang
   - Rspack
   - Rollup

integrationTests/README.md

@@ -14,6 +14,10 @@ Each subdirectory represents a different environment/bundler:
 - `ts` - tests for supported Typescript versions
 - `webpack` - tests for Webpack
 
+### Verifying Conditional Exports
+
+The `conditions` subdirectory contains tests that verify the conditional exports of GraphQL.js. These tests ensure that the correct files are imported based on the environment being used.
+
 ### Verifying Development Mode Tests
 
 Each subdirectory represents a different environment/bundler demonstrating enabling development mode by setting the environment variable `NODE_ENV` to `development`.

integrationTests/conditions/check.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert';
+
+import { GraphQLObjectType as ESMGraphQLObjectType } from 'graphql';
+
+import { CJSGraphQLObjectType, cjsPath } from './cjs-importer.cjs';
+
+const moduleSync = process.env.MODULE_SYNC === 'true';
+const expectedExtension = moduleSync ? '.mjs' : '.js';
+assert.ok(
+  cjsPath.endsWith(expectedExtension),
+  `require('graphql') should resolve to a file with extension "${expectedExtension}", but got "${cjsPath}".`,
+);
+
+const isSameModule = ESMGraphQLObjectType === CJSGraphQLObjectType;
+assert.strictEqual(
+  isSameModule,
+  true,
+  'ESM and CJS imports should be the same module instances.',
+);
+
+console.log('Module identity and path checks passed.');

integrationTests/conditions/cjs-importer.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+const { GraphQLObjectType } = require('graphql');
+
+const cjsPath = require.resolve('graphql');
+
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  CJSGraphQLObjectType: GraphQLObjectType,
+  cjsPath,
+};

integrationTests/conditions/package.json

@@ -0,0 +1,10 @@
+{
+  "description": "graphql-js should be loaded correctly on different versions of Node.js, Deno and Bun",
+  "private": true,
+  "scripts": {
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "graphql": "file:../graphql.tgz"
+  }
+}

integrationTests/conditions/test.js

@@ -0,0 +1,31 @@
+import childProcess from 'node:child_process';
+
+const nodeTests = [
+  // Old node versions, require => CJS
+  { version: '20.18.0', moduleSync: false },
+  { version: '22.11.0', moduleSync: false },
+  // New node versions, module-sync => ESM
+  { version: '20.19.0', moduleSync: true },
+  { version: '22.12.0', moduleSync: true },
+  { version: '24.0.0', moduleSync: true },
+];
+
+for (const { version, moduleSync } of nodeTests) {
+  console.log(`Testing on node@${version} (moduleSync: ${moduleSync}) ...`);
+  childProcess.execSync(
+    `docker run --rm --volume "$PWD":/usr/src/app -w /usr/src/app --env MODULE_SYNC=${moduleSync} node:${version}-slim node ./check.mjs`,
+    { stdio: 'inherit' },
+  );
+}
+
+console.log('Testing on bun (moduleSync: true) ...');
+childProcess.execSync(
+  `docker run --rm --volume "$PWD":/usr/src/app -w /usr/src/app --env MODULE_SYNC=true oven/bun:alpine bun ./check.mjs`,
+  { stdio: 'inherit' },
+);
+
+console.log('Testing on deno (moduleSync: false) ...');
+childProcess.execSync(
+  `docker run --rm --volume "$PWD":/usr/src/app -w /usr/src/app --env MODULE_SYNC=false denoland/deno:alpine-2.4.1 deno run --allow-read --allow-env ./check.mjs`,
+  { stdio: 'inherit' },
+);

integrationTests/ts/esm.ts

@@ -18,7 +18,7 @@ const queryType: GraphQLObjectType = new GraphQLObjectType({
           default: { value: 'World' },
         },
       },
-      resolve(_root, args: { who: string }) {
+      resolve(_root: unknown, args: { who: string }) {
         return 'Hello ' + args.who;
       },
     },

integrationTests/ts/extensions-test.ts

@@ -5,6 +5,8 @@ interface SomeExtension {
   meaningOfLife: 42;
 }
 
+// Import added to support deno, which does not scan node_modules automatically.
+import 'graphql';
 declare module 'graphql' {
   interface GraphQLObjectTypeExtensions<_TSource, _TContext> {
     someObjectExtension?: SomeExtension;
@@ -32,7 +34,8 @@ const queryType: GraphQLObjectType = new GraphQLObjectType({
           },
         },
       },
-      resolve: (_root, args) => 'Hello ' + (args.who || 'World'),
+      resolve: (_root: unknown, args: { who: string }) =>
+        'Hello ' + (args.who || 'World'),
       extensions: {
         someFieldExtension: { meaningOfLife: 42 },
       },

integrationTests/ts/package.json

@@ -8,6 +8,7 @@
   "dependencies": {
     "graphql": "file:../graphql.tgz",
     "graphql-esm": "file:../graphql-esm.tgz",
+    "@types/node": "~24.0.10",
     "typescript-4.9": "npm:[email protected]",
     "typescript-5.0": "npm:[email protected]",
     "typescript-5.1": "npm:[email protected]",

integrationTests/ts/test.js

@@ -9,10 +9,16 @@ const tsVersions = Object.keys(dependencies)
   .sort((a, b) => b.localeCompare(a));
 
 for (const version of tsVersions) {
-  console.log(`Testing on ${version} ...`);
+  console.log(`Testing on node ${version} ...`);
   childProcess.execSync(tscPath(version), { stdio: 'inherit' });
 }
 
+console.log('Testing on deno ...');
+childProcess.execSync(
+  `docker run --rm --volume "$PWD":/usr/src/app -w /usr/src/app denoland/deno:alpine-2.4.1 deno check`,
+  { stdio: 'inherit' },
+);
+
 function tscPath(version) {
   return path.join('node_modules', version, 'bin', 'tsc');
 }

resources/build-npm.ts

@@ -6,6 +6,7 @@ import ts from 'typescript';
 
 import { changeExtensionInImportPaths } from './change-extension-in-import-paths.js';
 import { inlineInvariant } from './inline-invariant.js';
+import type { ConditionalExports } from './utils.js';
 import {
   prettify,
   readPackageJSON,
@@ -98,18 +99,35 @@ async function buildPackage(outDir: string, isESMOnly: boolean): Promise<void> {
       }
     }
 
-    // Temporary workaround to allow "internal" imports, no grantees provided
     packageJSON.exports['./*.js'] = './*.js';
     packageJSON.exports['./*'] = './*.js';
 
     packageJSON.publishConfig.tag += '-esm';
     packageJSON.version += '+esm';
   } else {
     delete packageJSON.type;
-    packageJSON.main = 'index';
+    packageJSON.main = 'index.js';
     packageJSON.module = 'index.mjs';
-    emitTSFiles({ outDir, module: 'commonjs', extension: '.js' });
+    packageJSON.types = 'index.d.ts';
+
+    const { emittedTSFiles } = emitTSFiles({
+      outDir,
+      module: 'commonjs',
+      extension: '.js',
+    });
     emitTSFiles({ outDir, module: 'es2020', extension: '.mjs' });
+
+    packageJSON.exports = {};
+    for (const filepath of emittedTSFiles) {
+      if (path.basename(filepath) === 'index.js') {
+        const relativePath = './' + path.relative('./npmDist', filepath);
+        packageJSON.exports[path.dirname(relativePath)] =
+          buildExports(relativePath);
+      }
+    }
+
+    packageJSON.exports['./*.js'] = buildExports('./*.js');
+    packageJSON.exports['./*'] = buildExports('./*.js');
   }
 
   const packageJsonPath = `./${outDir}/package.json`;
@@ -141,21 +159,31 @@ function emitTSFiles(options: {
 
   const tsHost = ts.createCompilerHost(tsOptions);
   tsHost.writeFile = (filepath, body) => {
-    if (filepath.match(/.js$/) && extension === '.mjs') {
-      let bodyToWrite = body;
-      bodyToWrite = bodyToWrite.replace(
-        '//# sourceMappingURL=graphql.js.map',
-        '//# sourceMappingURL=graphql.mjs.map',
-      );
-      writeGeneratedFile(filepath.replace(/.js$/, extension), bodyToWrite);
-    } else if (filepath.match(/.js.map$/) && extension === '.mjs') {
-      writeGeneratedFile(
-        filepath.replace(/.js.map$/, extension + '.map'),
-        body,
-      );
-    } else {
-      writeGeneratedFile(filepath, body);
+    if (extension === '.mjs') {
+      if (filepath.match(/.js$/)) {
+        let bodyToWrite = body;
+        bodyToWrite = bodyToWrite.replace(
+          '//# sourceMappingURL=graphql.js.map',
+          '//# sourceMappingURL=graphql.mjs.map',
+        );
+        writeGeneratedFile(filepath.replace(/.js$/, extension), bodyToWrite);
+        return;
+      }
+
+      if (filepath.match(/.js.map$/)) {
+        writeGeneratedFile(
+          filepath.replace(/.js.map$/, extension + '.map'),
+          body,
+        );
+        return;
+      }
+
+      if (filepath.match(/.d.ts$/)) {
+        writeGeneratedFile(filepath.replace(/.d.ts$/, '.d.mts'), body);
+        return;
+      }
     }
+    writeGeneratedFile(filepath, body);
   };
 
   const tsProgram = ts.createProgram(['src/index.ts'], tsOptions, tsHost);
@@ -172,3 +200,16 @@ function emitTSFiles(options: {
     emittedTSFiles: tsResult.emittedFiles.sort((a, b) => a.localeCompare(b)),
   };
 }
+
+function buildExports(filepath: string): ConditionalExports {
+  const { dir, name } = path.parse(filepath);
+  const base = `./${path.join(dir, name)}`;
+  return {
+    module: `${base}.mjs`,
+    bun: `${base}.mjs`,
+    'module-sync': `${base}.mjs`,
+    node: `${base}.js`,
+    require: `${base}.js`,
+    default: `${base}.mjs`,
+  };
+}

resources/integration-test.ts

@@ -39,6 +39,9 @@ describe('Integration Tests', () => {
   testOnNodeProject('node');
   testOnNodeProject('webpack');
 
+  // Conditional export tests
+  testOnNodeProject('conditions');
+
   // Development mode tests
   testOnNodeProject('dev-node');
   testOnNodeProject('dev-deno');

resources/utils.ts

@@ -234,7 +234,7 @@ interface PackageJSON {
   repository?: { url?: string };
   scripts?: { [name: string]: string };
   type?: string;
-  exports: { [path: string]: string };
+  exports: { [path: string]: string | ConditionalExports };
   types?: string;
   typesVersions: { [ranges: string]: { [path: string]: Array<string> } };
   devDependencies?: { [name: string]: string };
@@ -245,6 +245,15 @@ interface PackageJSON {
   module?: string;
 }
 
+export interface ConditionalExports {
+  module: string;
+  bun: string;
+  'module-sync': string;
+  node: string;
+  require: string;
+  default: string;
+}
+
 export function readPackageJSON(
   dirPath: string = localRepoPath(),
 ): PackageJSON {

website/pages/upgrade-guides/v16-v17.mdx

@@ -16,6 +16,25 @@ import { Callout } from 'nextra/components'
 
 The v17 release drops support for end-of-life versions of Node.JS, retaining support for versions 20, 22, and 24 or above.
 
+## ESM and conditional exports
+
+Earlier versions of GraphQL.js shipped dual builds for CommonJS and ESM, with ESM ".mjs" files sitting alongside CommonJS ".js" files.
+The ESM build was accessible via tooling recognizing the `module` field in `package.json`, while the CommonJS build was accessible via
+the `main` field. Unless configured carefully, this could sometimes lead to multiple copies of GraphQL.js being loaded in the same
+process, i.e. the dual-package hazard.
+
+v17 enables access to the ESM build via the `exports` field in `package.json` in a scheme designed to avoid the dual-package hazard as
+best as possible, relying on the ability of bun and newer versions of Node.js to consistently load ESM modules via `require` by
+indicating support for specific conditions. __ESM will now be served by default__, unless the requesting environment tooling __both__
+(A) supports the `node` or `require` conditions __and__ (B) does NOT support `bun`, `module`, `module-sync`. In that scenario, the
+CommonJS build will be served instead.
+
+Note: ESM is not served to deno even though it supports require(esm) because deno not yet support the `module-sync` condition, nor
+does it seem to provide the `deno` condition when calling `require`, see https://github.com/denoland/deno/issues/29970.
+
+Deno users can access a Typescript build for deno via git://github.com/graphql/graphql-js.git#deno as well as by specifically loading
+the index.mjs file, i.e. `import { graphql } from 'graphql/index.mjs'`, although this does not protect against the dual-package hazard.
+
 ## Default values
 
 GraphQL schemas allow default values for input fields and arguments. Historically, GraphQL.js did not rigorously validate or coerce these