use development condition and enableDevMode() instead of NODE_ENV (#4464)

Motivation:

This PR makes our build product cross-platform by dropping all Node.js specific code.

In development mode, GraphQL.JS can provide an additional runtime check appropriate for development-time errors: the erroneous inclusion of multiple GraphQL.JS modules.

Unlike earlier versions of GraphQL.JS, by default, development mode is disabled. This is to best ensure that production builds do not incur the performance and bundle size penalties associated with the additional checks.

Also, unlike earlier versions, development mode is not configured by use of environment variables, which are accessed in disparate ways on the various platforms. In particular, the `NODE_ENV` environment variable now has no effect on triggering development mode. Rather, development mode is either enabled:
1. by setting a 'development' condition, which is possible only on platforms that support `package.json` conditional exports and custom conditions, or
2. by calling `enableDevMode()` within user code.

Conditional exports with custom conditions are supported by: Node.js, Deno, Bun, Webpack 5, Rspack, Rollup (via the `node-resolve` plugin), esbuild, Vite, and Rsbuild. create-react-app and Next.js support conditional exports when using Webpack 5 as their bundler.

Conditional exports with custom conditions are not supported by Webpack 4, Rollup (without the `node-resolve` plugin), older versions of Deno or transpilers such as swc. create-react-app and Next.js do not support conditional exports with custom conditions when using Webpack 4 as their bundler, nor does Next.js yet support conditional exports with custom conditions when using Turbopack (see vercel/next.js#78912).

Testing frameworks such as Mocha, Jest, and Vitest support conditional exports with custom conditions,

Integration tests within the repository demonstrate how to enable development mode using the `development` condition on various platforms that support this, as well as enabling development mode by calling `enableDevMode()` within user code.

We encourage enabling development mode in a development environment. This facilitates the additional check to ensure that only a single GraphQL.JS module is used. Additional development-time checks may also be added in the future.

Author: yaacovCR

cspell.yml

@@ -68,8 +68,11 @@ words:
   - deno
   - denoland
   - hashbang
-  - Rspack
+  - vitest
   - Rollup
+  - Rspack
+  - Rsbuild
+  - Turbopack
 
   # Website tech
   - Nextra

integrationTests/README.md

@@ -20,7 +20,7 @@ The `conditions` subdirectory contains tests that verify the conditional exports
 
 ### Verifying Development Mode Tests
 
-Each subdirectory represents a different environment/bundler demonstrating enabling development mode by setting the environment variable `NODE_ENV` to `development`.
+Each subdirectory represents a different platform/bundler demonstrating enabling development mode by enabling the `development` condition or by calling `enableDevMode()`.
 
 ### Verifying Production Mode Tests
 

integrationTests/dev-bun/package.json

@@ -2,7 +2,7 @@
   "description": "graphql-js development mode should work with Bun",
   "private": true,
   "scripts": {
-    "test": "docker run --rm --volume \"$PWD\":/usr/src/app -w /usr/src/app oven/bun:\"$BUN_VERSION\"-slim bun test.js"
+    "test": "docker run --rm --volume \"$PWD\":/usr/src/app -w /usr/src/app oven/bun:\"$BUN_VERSION\"-slim bun --conditions=development test.js"
   },
   "dependencies": {
     "graphql": "file:../graphql.tgz"

integrationTests/dev-deno/package.json

@@ -2,7 +2,7 @@
   "description": "graphql-js development mode should work with Deno",
   "private": true,
   "scripts": {
-    "test": "docker run --rm --volume \"$PWD\":/usr/src/app -w /usr/src/app denoland/deno:alpine-\"$DENO_VERSION\" deno run --allow-env=NODE_ENV test.js"
+    "test": "docker run --rm --volume \"$PWD\":/usr/src/app -w /usr/src/app denoland/deno:alpine-\"$DENO_VERSION\" deno run --conditions=development test.js"
   },
   "dependencies": {
     "graphql": "file:../graphql.tgz"

integrationTests/dev-deno/test.js

@@ -9,7 +9,7 @@ class GraphQLObjectType {
 try {
   isObjectType(new GraphQLObjectType());
   throw new Error(
-    'Expected isObjectType to throw an error in Deno implicit dev mode.',
+    'Expected isObjectType to throw an error in Deno development mode.',
   );
 } catch (error) {
   if (!error.message.includes('from another module or realm')) {

integrationTests/dev-esbuild/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "esbuild index.js --bundle --outfile=dist/bundle.js --format=esm",
+    "build": "esbuild index.js --bundle --outfile=dist/bundle.js --format=esm --conditions=development",
     "test": "npm run build && node dist/bundle.js"
   },
   "dependencies": {

integrationTests/dev-explicit/package.json

@@ -0,0 +1,11 @@
+{
+  "description": "graphql-js explicit development mode should work",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "dependencies": {
+    "graphql": "file:../graphql.tgz"
+  }
+}

integrationTests/dev-explicit/test.js

@@ -0,0 +1,20 @@
+import { enableDevMode, isObjectType } from 'graphql';
+
+enableDevMode();
+
+class GraphQLObjectType {
+  get [Symbol.toStringTag]() {
+    return 'GraphQLObjectType';
+  }
+}
+
+try {
+  isObjectType(new GraphQLObjectType());
+  throw new Error(
+    'Expected isObjectType to throw an error in Node.js development mode.',
+  );
+} catch (error) {
+  if (!error.message.includes('from another module or realm')) {
+    throw error;
+  }
+}

integrationTests/dev-jest/index.test.js

@@ -9,7 +9,7 @@ class FakeGraphQLObjectType {
   }
 }
 
-describe('Jest with SWC development mode tests', () => {
+describe('Jest development mode tests', () => {
   test('isObjectType should throw in development mode for instances from another realm/module', () => {
     expect(() => isObjectType(new FakeGraphQLObjectType())).toThrowError(
       /from another module or realm/,

integrationTests/dev-jest/jest.config.js

@@ -0,0 +1,8 @@
+const jestConfig = {
+  testEnvironmentOptions: {
+    customExportConditions: ['development'],
+  },
+};
+
+// eslint-disable-next-line no-restricted-exports, import/no-default-export
+export default jestConfig;