Development Mode

In development mode, GraphQL.JS can provides additional runtime check appropriate for development-time errors, including primarily 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. explicitly, by calling enableDevMode() or
2. implicitly, by setting the ‘development’ condition, which is possible only on platforms that support package.json conditional exports and custom conditions.

Conditional exports are supported by: Node.js, Deno (canary), 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 are not supported by Deno (current), Webpack 4, Rollup (without the node-resolve plugin), or swc. create-react-app and Next.js do not support conditional exports when using Webpack 4 as their bundler, nor does Next.js yet support conditional exports when using Turbopack (see https://github.com/vercel/next.js/discussions/78912).

We encourage enabling development mode in a development environment, either explicitly or implicitly. This allows for an additional check to ensure that only a single GraphQL.JS module is used. Additional development-time checks may also be added in the future.

First, we will discuss the implications of using multiple GraphQL.JS modules, and then we will share additional details for how to enable development mode on various platforms.

Multiple Graphql.JS Modules

Only a single GraphQL.JS can be used within a project. Different GraphQL.JS versions cannot be used at the same time since different versions may have different capabilities and behavior. The data from one version used in the function from another could produce confusing and spurious results.

Duplicate modules of GraphQL.JS of the same version may also fail at runtime, sometimes in unexpected ways. This is because GraphQL.JS relies on the identity of the module for key features. Most significantly, instanceof checks are used throughout GraphQL.JS to identify and distinguish between GraphQL schema elements, such as the particular GraphQL type. Also, special exported constants like BREAK allow library users to manipulate visitor behavior, also relying on the module identity.

To ensure that only a single GraphQL.JS module is used, all libraries depending on GraphQL.JS should use the appropriate peer dependency mechanism, as provided by their package manager, bundler, build tool, or runtime.

In development mode, GraphQL.JS provides a validation check triggered by any use of instanceof that should catch most cases of multiple GraphQL.js modules being used in the same project.

This additional validation is unnecessary in production, where the GraphQL.js library is expected to be have been setup correctly as a single module. So as to avoid the performance and bundle size overhead this check entails, it is only included when the development exports condition is explicitly enabled or when the enableDevMode() module is called.

Enabling Development Mode

A Catch-All Option: Explicit Enabling of Development Mode

Development mode may be enabled explicitly by calling enableDevMode():

// entrypoint.js
import { enableDevMode } from 'graphql';
enableDevMode();

A bootstrapping file can be used to enable development mode conditionally:

// bootstrap.js
import process from 'node:process';
import { enableDevMode } from 'graphql';
if (process.env.NODE_ENV === 'development') {
  enableDevMode();
}
import './path/to/my/entry.js';

The above is compatible with Node.js; the exact environment variable and method of accessing it depends on the individual platform.

Conditional Exports and Implicit Enabling of Development Mode

Depending on your platform, you may be able to use the ‘development’ condition to enable development mode without the need for an explicit import.

Node.js

In Node.js, the development condition can be enabled by passing the --conditions=development flag to the Node.js runtime. This can be done within package.json scripts:

{
  "scripts": {
    "start": "node --conditions=development index.js"
  }
}

Alternatively, this can be included within the NODE_OPTIONS environment variable:

export NODE_OPTIONS=development

Deno

In Deno, conditional exports are not yet released, but are available within the latest canary build as follows:

deno run --conditions=development main.js

Alternatively, within the canary build, this can be included within the DENO_CONDITIONS environment variable:

export DENO_CONDITIONS=development

Bun

In Bun, you can also enable the development condition by passing the --conditions=development to the runtime:

bun --conditions=development main.js

Webpack

Webpack 5 supports the ‘development’ condition natively and requires no additional configuration.

Rollup

Rollup supports the ‘development’ condition only when using the @rollup/plugin-node-resolve plugin.

//rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
 
export default {
  plugins: [
    resolve({
      exportConditions: ['development'],
    })
  ]
};

esbuild

When using esbuild, you can enable the ‘development’ condition by setting the --conditions=development flag in your build command:

esbuild --conditions=development entrypoint.js

Note that setting any custom conditions will drop the default ‘module’ condition (used to avoid the dual package hazard), so you may need to use:

esbuild --conditions=development,module entrypoint.js

See further discussion within the esbuild documentation for more details.

Vite

Vite supports the ‘development’ condition natively and requires no additional configuration.

Next.js

When using Webpack 5 as its bundler, Next.js supports the ‘development’ condition natively and require no additional configuration. When using Webpack 4 or Turbopack, development mode must be enabled explicitly.

create-react-app

When using Webpack 5 as its bundler, create-react-app support the ‘development’ condition natively and requires no additional configuration. When using Webpack 4, development mode must be enabled explicitly.