chore: add info about ES modules to docs (#10611)

docs/ECMAScriptModules.md

@@ -0,0 +1,16 @@
+---
+id: ecmascript-modules
+title: ECMAScript Modules
+---
+
+Jest ships with _experimental_ support for ECMAScript Modules (ESM).
+
+> Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
+
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+
+With the warnings out of the way, this is how you activate ESM support in your tests.
+
+1. Ensure you either disable [code transforms](./configuration#transform-objectstring-pathtotransformer--pathtotransformer-object) by passing `transform: {}` or otherwise configure your transformer to emit ESM rather than the default CommonJS (CJS).
+1. Execute `node` with `--experimental-vm-modules`, e.g. `node --experimental-vm-modules node_modules/.bin/jest` or `NODE_OPTIONS=--experimental-vm-modules npx jest` etc.
+1. Beyond that, we attempt to follow `node`'s logic for activating "ESM mode" (such as looking at `type` in `package.json` or `mjs` files), see [their docs](https://nodejs.org/api/esm.html#esm_enabling) for details

website/sidebars.json

@@ -17,6 +17,7 @@
       "manual-mocks",
       "es6-class-mocks",
       "bypassing-module-mocks",
+      "ecmascript-modules",
       "webpack",
       "puppeteer",
       "mongodb",

website/versioned_docs/version-26.0/ECMAScriptModules.md

@@ -0,0 +1,17 @@
+---
+id: version-26.0-ecmascript-modules
+title: ECMAScript Modules
+original_id: ecmascript-modules
+---
+
+Jest ships with _experimental_ support for ECMAScript Modules (ESM).
+
+> Note that due to its experimental nature there are many bugs and missing features in Jest's implementation, both known and unknown. You should check out the [tracking issue](https://github.com/facebook/jest/issues/9430) and the [label](https://github.com/facebook/jest/labels/ES%20Modules) on the issue tracker for the latest status.
+
+> Also note that the APIs Jest uses to implement ESM support is still [considered experimental by Node](https://nodejs.org/api/vm.html#vm_class_vm_module) (as of version `14.13.1`).
+
+With the warnings out of the way, this is how you activate ESM support in your tests.
+
+1. Ensure you either disable [code transforms](./configuration#transform-objectstring-pathtotransformer--pathtotransformer-object) by passing `transform: {}` or otherwise configure your transformer to emit ESM rather than the default CommonJS (CJS).
+1. Execute `node` with `--experimental-vm-modules`, e.g. `node --experimental-vm-modules node_modules/.bin/jest` or `NODE_OPTIONS=--experimental-vm-modules npx jest` etc.
+1. Beyond that, we attempt to follow `node`'s logic for activating "ESM mode" (such as looking at `type` in `package.json` or `mjs` files), see [their docs](https://nodejs.org/api/esm.html#esm_enabling) for details

website/versioned_sidebars/version-26.0-sidebars.json

@@ -0,0 +1,45 @@
+{
+  "version-26.0-docs": {
+    "Introduction": [
+      "version-26.0-getting-started",
+      "version-26.0-using-matchers",
+      "version-26.0-asynchronous",
+      "version-26.0-setup-teardown",
+      "version-26.0-mock-functions",
+      "version-26.0-jest-platform",
+      "version-26.0-jest-community",
+      "version-26.0-more-resources"
+    ],
+    "Guides": [
+      "version-26.0-snapshot-testing",
+      "version-26.0-tutorial-async",
+      "version-26.0-timer-mocks",
+      "version-26.0-manual-mocks",
+      "version-26.0-es6-class-mocks",
+      "version-26.0-bypassing-module-mocks",
+      "version-26.0-ecmascript-modules",
+      "version-26.0-webpack",
+      "version-26.0-puppeteer",
+      "version-26.0-mongodb",
+      "version-26.0-dynamodb",
+      "version-26.0-tutorial-jquery",
+      "version-26.0-watch-plugins",
+      "version-26.0-migration-guide",
+      "version-26.0-troubleshooting",
+      "version-26.0-architecture"
+    ],
+    "Framework Guides": [
+      "version-26.0-tutorial-react",
+      "version-26.0-tutorial-react-native",
+      "version-26.0-testing-frameworks"
+    ],
+    "API Reference": [
+      "version-26.0-api",
+      "version-26.0-expect",
+      "version-26.0-mock-function-api",
+      "version-26.0-jest-object",
+      "version-26.0-configuration",
+      "version-26.0-cli"
+    ]
+  }
+}