diff --git a/docs/ECMAScriptModules.md b/docs/ECMAScriptModules.md new file mode 100644 index 000000000000..40320348203a --- /dev/null +++ b/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 diff --git a/website/sidebars.json b/website/sidebars.json index de65d7d26007..3c4cc29d4399 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -17,6 +17,7 @@ "manual-mocks", "es6-class-mocks", "bypassing-module-mocks", + "ecmascript-modules", "webpack", "puppeteer", "mongodb", diff --git a/website/versioned_docs/version-26.0/ECMAScriptModules.md b/website/versioned_docs/version-26.0/ECMAScriptModules.md new file mode 100644 index 000000000000..b99d6400478b --- /dev/null +++ b/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 diff --git a/website/versioned_sidebars/version-26.0-sidebars.json b/website/versioned_sidebars/version-26.0-sidebars.json new file mode 100644 index 000000000000..c69d3ac005d8 --- /dev/null +++ b/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" + ] + } +}