Skip to content

Commit 7445e8e

Browse files
yaacovCRyaacovCR
committed
update docs
1 parent ef851e0 commit 7445e8e

File tree

5 files changed

+220
-133
lines changed

5 files changed

+220
-133
lines changed

‎cspell.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ overrides:
4040
- tada
4141
- Graphile
4242
- precompiled
43-
- debuggable
43+
- Rollup
44+
- Turbopack
4445

4546
validateDirectives: true
4647
ignoreRegExpList:

‎website/pages/docs/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ const meta = {
4141
type: 'separator',
4242
title: 'Production & Scaling',
4343
},
44+
'development-mode': '',
4445
'going-to-production': '',
4546
'scaling-graphql': '',
4647
};

‎website/pages/docs/development-mode.mdx

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
title: Development Mode
3+
---
4+
5+
# Development Mode
6+
7+
In development mode, GraphQL.JS can provides additional runtime check appropriate for
8+
development-time errors, including primarily the erroneous inclusion of multiple
9+
GraphQL.JS modules.
10+
11+
Unlike earlier versions of GraphQL.JS, by default, development mode is disabled.
12+
This is to best ensure that production builds do not incur the performance and bundle
13+
size penalties associated with the additional checks.
14+
15+
Also, unlike earlier versions, development mode is not configured by use of
16+
environment variables, which are accessed in disparate ways in varying environments.
17+
In particular, the `NODE_ENV` environment variable now has no effect on triggering
18+
development mode. Rather, development mode is either enabled:
19+
1. explicitly, by importing `graphql/dev` prior to other Graphql.JS imports or
20+
2. implicitly, by setting the 'development' condition, which is possible only in
21+
environments that support `package.json` conditional exports and custom conditions.
22+
23+
Conditional exports are supported by: Node.js, Deno (canary), Bun, Webpack 5, Rollup
24+
(via the `node-resolve` plugin), esbuild, and Vite. create-react-app and Next.js
25+
support conditional exports when using Webpack 5 as their bundler.
26+
27+
Conditional exports are not supported by Deno (current), Webpack 4, Rollup (without
28+
the `node-resolve` plugin), or swc. create-react-app and Next.js do not support
29+
conditional exports when using Webpack 4 as their bundler, nor does Next.js yet
30+
support conditional exports when using Turbopack (see
31+
https://github.com/vercel/next.js/discussions/78912).
32+
33+
We encourage enabling development mode within the development environments, either
34+
explicitly or implicitly. Additional development-time checks may also be added in the future.
35+
For now, the primary check is to ensure that only a single GraphQL.JS module is used.
36+
First, we will discuss the implications of using multiple GraphQL.JS modules, and then
37+
we will share additional details for how to enable development mode in various environments.
38+
39+
## Multiple Graphql.JS Modules
40+
41+
Only a single GraphQL.JS can be used within a project. Different GraphQL.JS versions cannot be
42+
used at the same time since different versions may have different capabilities and behavior.
43+
The data from one version used in the function from another could produce confusing and spurious
44+
results.
45+
46+
Duplicate modules of GraphQL.JS of the same version may also fail at runtime, sometimes in
47+
unexpected ways. This is because GraphQL.JS relies on the identity of the module for
48+
key features. Most significantly, `instanceof` checks are used throughout GraphQL.JS to
49+
identify and distinguish between GraphQL schema elements, such as the particular GraphQL type.
50+
Also, special exported constants like `BREAK` allow library users to manipulate visitor
51+
behavior, also relying on the module identity.
52+
53+
To ensure that only a single GraphQL.JS module is used, all libraries depending on GraphQL.JS
54+
should use the appropriate peer dependency mechanism, as provided by their package manager,
55+
bundler, build tool, or runtime environment.
56+
57+
In development, GraphQL.JS provides a validation check triggered by any use of `instanceof`
58+
that should catch most cases of multiple GraphQL.js modules being used in the same project.
59+
60+
This additional validation is unnecessary in production, where the GraphQL.js library is
61+
expected to be have been setup correctly as a single module. So as to avoid the performance
62+
and bundle size overhead this check entails, it is only included when the `development`
63+
exports condition is explicitly enabled or when the `graphql/dev` module is
64+
explicitly imported before any other GraphQL.JS import.
65+
66+
## Enabling Development Mode
67+
68+
### A Catch-All Option: Explicit Enabling of Development Mode
69+
70+
Development mode is activated by importing the `graphql/dev` module before
71+
any other GraphQL.js import. Introducing a new bootstrapping entrypoint simplifies this
72+
workflow:
73+
74+
```js
75+
// bootstrap.js
76+
import 'graphql/dev';
77+
import './path/to/my/original-entry-point.js';
78+
```
79+
80+
The bootstrapping file can be used to enable development mode conditionally:
81+
82+
```js
83+
import process from 'node:process';
84+
// bootstrap.js
85+
if (process.env.NODE_ENV === 'development') {
86+
await import('graphql/dev');
87+
}
88+
import './path/to/my/entry.js';
89+
```
90+
91+
The above boiler plate is compatible with Node.js; the exact environment variable and method
92+
of accessing it depends on the individual environment and desired variable.
93+
94+
95+
### Conditional Exports and Implicit Enabling of Development Mode
96+
97+
Depending on your environment, you may be able to use the 'development' condition
98+
to enable development mode without the need for an explicit import.
99+
100+
### Node.js
101+
102+
In Node.js, the development condition can be enabled by passing the `--conditions=development`
103+
flag to the Node.js runtime. This can be done within `package.json` scripts:
104+
105+
```json
106+
{
107+
"scripts": {
108+
"start": "node --conditions=development index.js"
109+
}
110+
}
111+
```
112+
113+
Alternatively, this can be included within the `NODE_OPTIONS` environment variable:
114+
115+
```bash
116+
export NODE_OPTIONS="--conditions=development"
117+
```
118+
119+
#### Deno
120+
121+
In Deno, conditional exports are not yet released, but are available within the canary build
122+
(see https://github.com/denoland/deno/issues/23757) as follows:
123+
124+
```bash
125+
deno run --unstable-node-conditions=development main.js
126+
```
127+
128+
#### Bun
129+
130+
In Bun, you can enable the development condition by passing the `--conditions=development` flag
131+
when running your script:
132+
133+
```bash
134+
bun --conditions=development main.js
135+
```
136+
137+
#### Webpack
138+
139+
Webpack 5 supports the 'development' condition natively and requires no additional configuration.
140+
141+
### Rollup
142+
143+
Rollup supports the 'development' condition only when using the `@rollup/plugin-node-resolve` plugin.
144+
145+
```ts
146+
//rollup.config.js
147+
import resolve from '@rollup/plugin-node-resolve';
148+
149+
export default {
150+
plugins: [
151+
resolve({
152+
exportConditions: ['development'],
153+
})
154+
]
155+
};
156+
```
157+
158+
### esbuild
159+
160+
When using esbuild, you can enable the 'development' condition by setting the `--conditions=development`
161+
flag in your build command:
162+
163+
```bash
164+
esbuild --conditions=development entrypoint.js
165+
```
166+
167+
Note that setting any custom conditions will drop the default 'module' condition (used to avoid the dual
168+
package hazard), so you may need to use:
169+
170+
```bash
171+
esbuild --conditions=development,module entrypoint.js
172+
```
173+
174+
See further discussion within the [esbuild documentation](https://esbuild.github.io/api/#conditions) for
175+
more details.
176+
177+
### Vite
178+
179+
Vite supports the 'development' condition natively and requires no additional configuration.
180+
181+
### Next.js
182+
183+
When using Webpack 5 as its bundler, Next.js supports the 'development' condition natively
184+
and require no additional configuration. When using Webpack 4 or Turbopack, development mode
185+
must be enabled explicitly.
186+
187+
### create-react-app
188+
189+
When using Webpack 5 as its bundler, create-react-app support the 'development' condition
190+
natively and requires no additional configuration. When using Webpack 4, development mode
191+
must be enabled explicitly.

‎website/pages/docs/going-to-production.mdx

Lines changed: 5 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -4,142 +4,15 @@ title: Going to Production
44

55
# Going to Production
66

7-
GraphQL.JS contains a few development checks which in production will cause slower performance and
8-
an increase in bundle-size. Every bundler goes about these changes different, in here we'll list
9-
out the most popular ones.
7+
GraphQL.JS contains a few development-mode checks which cause slower performance and an increase
8+
in bundle size. As discussing within the [Development Mode](./development-mode) section,
9+
development mode is disabled by default, but if you have enabled it in your development
10+
environment, verify that you have not also enabled it in production.
1011

11-
GraphQL.js includes development-time checks that are useful during local testing but should
12-
be disabled in production to reduce overhead. Additional concerns include caching, error handling,
13-
schema management, and operational monitoring.
12+
Additional concerns include caching, error handling, schema management, and operational monitoring.
1413

1514
This guide covers key practices to prepare a server built with GraphQL.js for production use.
1615

17-
## Optimize your build for production
18-
19-
In development, GraphQL.js includes validation checks to catch common mistakes like invalid schemas
20-
or resolver returns. These checks are not needed in production and can increase runtime overhead.
21-
22-
You can disable them by setting `process.env.NODE_ENV` to `'production'` during your build process.
23-
GraphQL.js will automatically skip over development-only code paths.
24-
25-
Bundlers are tools that compile and optimize JavaScript for deployment. Most can be configured to
26-
replace environment variables such as `process.env.NODE_ENV` at build time,
27-
allowing for unused code (such as development only code paths) to be elided by
28-
minification tools.
29-
30-
### Bundler configuration examples
31-
32-
The following examples show how to configure common bundlers to set `process.env.NODE_ENV`
33-
and remove development-only code:
34-
35-
#### Vite
36-
37-
```js
38-
// vite.config.js
39-
import { defineConfig } from 'vite';
40-
41-
export default defineConfig({
42-
define: {
43-
'process.env.NODE_ENV': '"production"',
44-
},
45-
});
46-
```
47-
48-
#### Next.js
49-
50-
When you build your application with `next build` and run it using `next start`, Next.js sets
51-
`process.env.NODE_ENV` to `'production'` automatically. No additional configuration is required.
52-
53-
```bash
54-
next build
55-
next start
56-
```
57-
58-
If you run a custom server, make sure `NODE_ENV` is set manually.
59-
60-
#### Create React App (CRA)
61-
62-
To customize Webpack behavior in CRA, you can use a tool like [`craco`](https://craco.js.org/).
63-
This example uses CommonJS syntax instead of ESM syntax, which is required by `craco.config.js`:
64-
65-
```js
66-
// craco.config.js
67-
const webpack = require('webpack');
68-
69-
module.exports = {
70-
webpack: {
71-
plugins: [
72-
new webpack.DefinePlugin({
73-
'globalThis.process': JSON.stringify(true),
74-
'process.env.NODE_ENV': JSON.stringify('production'),
75-
}),
76-
],
77-
},
78-
};
79-
```
80-
81-
#### esbuild
82-
83-
```json
84-
{
85-
"define": {
86-
"globalThis.process": true,
87-
"process.env.NODE_ENV": "production"
88-
}
89-
}
90-
```
91-
92-
#### Webpack
93-
94-
```js
95-
// webpack.config.js
96-
import { fileURLToPath } from 'url';
97-
import { dirname } from 'path';
98-
99-
const __filename = fileURLToPath(import.meta.url);
100-
const __dirname = dirname(__filename);
101-
102-
export default {
103-
mode: 'production', // Automatically sets NODE_ENV
104-
context: __dirname,
105-
};
106-
```
107-
108-
#### Rollup
109-
110-
```js
111-
// rollup.config.js
112-
import replace from '@rollup/plugin-replace';
113-
114-
export default {
115-
plugins: [
116-
replace({
117-
preventAssignment: true,
118-
'process.env.NODE_ENV': JSON.stringify('production'),
119-
}),
120-
],
121-
};
122-
```
123-
124-
#### SWC
125-
126-
```json filename=".swcrc"
127-
{
128-
"jsc": {
129-
"transform": {
130-
"optimizer": {
131-
"globals": {
132-
"vars": {
133-
"globalThis.process": true,
134-
"process.env.NODE_ENV": "production"
135-
}
136-
}
137-
}
138-
}
139-
}
140-
}
141-
```
142-
14316
## Secure your schema
14417

14518
GraphQL gives clients a lot of flexibility, which can be a strength or a liability depending on

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,27 @@ import { Callout } from 'nextra/components'
1212

1313
# Breaking changes
1414

15+
## `graphql-js` === ESM-only secondary to improved `require(esm)` support
16+
17+
`graphql-js` has been converted to an ESM only library. Previously, the library included both CJS and ESM versions. This is primarily
18+
motivated by the release of unflagged support for synchronously `require()`-ing ESM-only modules (that --like our library-- do not use
19+
top-level `await`).
20+
21+
In conjunction with this change, we have bumped the minimum required Node.JS versions to `20.19.0`, `22.12.0`, or `23.0.0` and above.
22+
23+
For more information, see:
24+
- https://joyeecheung.github.io/blog/2024/03/18/require-esm-in-node-js/
25+
- https://nodejs.org/en/blog/release/v23.0.0
26+
- https://nodejs.org/en/blog/release/v22.12.0
27+
- https://nodejs.org/en/blog/release/v20.19.0
28+
29+
This exact behavior is also supported in other runtimes such as [Bun](https://bun.sh/docs/runtime/modules#top-level-await) and
30+
[Deno](https://docs.deno.com/runtime/fundamentals/node/#require(esm)).
31+
32+
## Development checks no longer depend on the `NODE_ENV` environment variable.
33+
34+
...
35+
1536
## Default values
1637

1738
GraphQL schemas allow default values for input fields and arguments. Historically, GraphQL.js did not rigorously validate or coerce these

0 commit comments

Comments
 (0)