From 0f8787275c918b6a9c63952a3df6ee6bbb33826f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Lytek?= <michal.wojciech.lytek@gmail.com>
Date: Wed, 19 Jul 2023 18:11:48 +0200
Subject: [PATCH] Add info about ESM support in docs

---
 CHANGELOG.md          |  1 +
 docs/esm.md           | 46 +++++++++++++++++++++++++++++++++++++++++++
 docs/installation.md  |  6 +++---
 tsconfig.esm.json     |  3 ++-
 website/i18n/en.json  |  3 +++
 website/sidebars.json |  3 ++-
 6 files changed, 57 insertions(+), 5 deletions(-)
 create mode 100644 docs/esm.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ac1bc488..d316f9f7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@
 - **Breaking Change**: exported `GraphQLISODateTime` scalar has now a name `DateTimeISO`
 - **Breaking Change**: change `ValidatorFn` signature from `ValidatorFn<TArgs>` to `ValidatorFn<TContext>`
 - support custom validation function getting resolver data on validate
+- bring compatibility with the ESM ecosystem by exposing the double bundle of the `type-graphql` package (CJS and ESM versions)
 
 ### Fixes
 
diff --git a/docs/esm.md b/docs/esm.md
new file mode 100644
index 000000000..ec2a4f446
--- /dev/null
+++ b/docs/esm.md
@@ -0,0 +1,46 @@
+---
+title: ECMAScript Modules
+---
+
+Since `v2.0.0` release, TypeGraphQL is compatible with ECMAScript modules.
+
+Thanks to this, we can `import` the `type-graphql` package in the ESM projects without any hassle.
+
+## TypeScript configuration
+
+It's important to properly configure the project, so that it uses ESM correctly:
+
+- the `module` options should be set to `ES2020/ES2022/ESNext`
+- for the NodeJS apps, we should set `moduleResolution` to `"node16"`
+
+All in all, the `tsconfig.json` file should looks like this:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "es2020",
+    "moduleResolution": "node16",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Package.json configuration
+
+It is also important to set `type` option to `"module"` in your `package.json` file:
+
+```json title="package.json"
+{
+  "type": "module"
+}
+```
+
+## Imports
+
+Apart from using `import` syntax, your local imports have to use the `.js` suffix, e.g.:
+
+```ts
+import { MyResolver } from "./resolvers/MyResolver.js";
+```
diff --git a/docs/installation.md b/docs/installation.md
index e409cfee6..62bd67351 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -39,11 +39,11 @@ It's important to set these options in the `tsconfig.json` file of our project:
 }
 ```
 
-`TypeGraphQL` is designed to work with Node.js LTS and the latest stable releases. It uses features from ES2019 so we should set our `tsconfig.json` file appropriately:
+`TypeGraphQL` is designed to work with Node.js LTS and the latest stable releases. It uses features from ES2021 so we should set our `tsconfig.json` file appropriately:
 
 ```js
 {
-  "target": "es2019" // Or newer if Node.js version supports it
+  "target": "es2021" // Or newer if Node.js version supports it
 }
 ```
 
@@ -52,7 +52,7 @@ All in all, the minimal `tsconfig.json` file example looks like this:
 ```json
 {
   "compilerOptions": {
-    "target": "es2019",
+    "target": "es2021",
     "module": "commonjs",
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true
diff --git a/tsconfig.esm.json b/tsconfig.esm.json
index 893872b61..10be2b905 100644
--- a/tsconfig.esm.json
+++ b/tsconfig.esm.json
@@ -1,7 +1,8 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "module": "esnext",
+    "module": "ES2020",
+    "moduleResolution": "node16",
     "outDir": "./build/esm"
   }
 }
diff --git a/website/i18n/en.json b/website/i18n/en.json
index 06499094b..67196e88e 100644
--- a/website/i18n/en.json
+++ b/website/i18n/en.json
@@ -32,6 +32,9 @@
       "enums": {
         "title": "Enums"
       },
+      "esm": {
+        "title": "ECMAScript Modules"
+      },
       "examples": {
         "title": "Examples",
         "sidebar_label": "List of examples"
diff --git a/website/sidebars.json b/website/sidebars.json
index 8490ec531..2ab18bdd9 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -6,7 +6,8 @@
       "getting-started",
       "types-and-fields",
       "resolvers",
-      "bootstrap"
+      "bootstrap",
+      "esm"
     ],
     "Advanced guides": [
       "scalars",