From e1e7563dced81a12214ebdabb088a56f8f6af5d8 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Sat, 9 Mar 2019 23:38:15 -0800
Subject: [PATCH 1/9] Announcement blog post, first draft

---
 doc/announcement.md | 99 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 doc/announcement.md

diff --git a/doc/announcement.md b/doc/announcement.md
new file mode 100644
index 0000000..bcc3d92
--- /dev/null
+++ b/doc/announcement.md
@@ -0,0 +1,99 @@
+# Announcing a New `--experimental-modules`
+
+Back in 2017, Node.js 8.9.0 shipped experimental support for [ECMAScript modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/), known for their `import` and `export` statements. This support was behind the flag `--experimental-modules`.
+
+A lot has happened since then. All major browsers [now support](https://caniuse.com/#feat=es6-module) ECMAScript modules (ES modules) via `<script type="module">`. Various projects have sprung up to make NPM packages with ES module sources available for use in browsers via `<script type="module">`. Support for [import maps](https://github.com/WICG/import-maps), which bring to browsers Node-style package names in `import` statements, [is coming to Chrome](https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/qYeQFqgFOyA/rXJapjMaEAAJ).
+
+All this progress toward adoption of ES modules has increased the urgency for Node.js to ship its support for ES modules. Especially now that there are other runtimes and environments where ES modules are in use, it’s more important than ever that Node.js join the JavaScript standard.
+
+Yet Node’s initial ES modules support has remained in an experimental state, largely due to strong pushback from the community to several decisions that were made in its design. In response, the [Modules Team](https://github.com/nodejs/modules) was formed to take a fresh look at implementing support for ES modules in Node.js. This has led to a [new implementation](https://github.com/nodejs/ecmascript-modules) for supporting ES modules, that we are pleased to announce will ship as part of Node.js 12. It will replace the old `--experimental-modules` implementation, behind the same flag. We hope that this new implementation addresses many of the community’s concerns, and can ship as part of Node.js proper, without a flag, before Node.js 12 reaches [LTS status](https://nodejs.org/en/about/releases/) in October 2019.
+
+## What’s in `--experimental-modules`
+
+Like the previous version, this new `--experimental-modules` adds support to Node.js for the following:
+
+- [ES2015 `import` statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) can reference JavaScript files that are themselves written using ES module syntax. Files can be referenced as relative URLs (`'./file.mjs'`), absolute `file://` URLs (`'file:///opt/app/file.mjs'`), package names (`'es-module-package'`) or paths within packages (`'es-module-package/lib/file.mjs'`).
+
+- `import` statements that reference ES module files can specify both the default export (`import _ from 'es-module-package'`) or named exports (`import { shuffle } from 'es-module-package'`). All Node.js built-in packages like `fs` and `path` support both default and named exports.
+
+- `import` statements that reference CommonJS files (all current JavaScript code written for Node.js, [using `require` and `module.exports`](https://nodejs.org/api/modules.html)) can use the CommonJS default export (`import _ from 'commonjs-package'`) only. _This is a work in progress and may change in the future._
+
+- [`export` statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) in ES module files can specify both default and named exports for `import` statements to reference.
+
+- Dynamic `import()` expressions can be used to import ES modules into either CommonJS or ES module files. Note that `import()` returns a promise.
+
+- `import.meta.url` provides the `file://` URL of the current ES module file.
+
+- Node.js can be run with an ES module file as a program’s initial entry point.
+
+- Loaders can be written to modify Node’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
+
+So if that’s what’s carried over from the previous implementation, what’s new?
+
+## `import` and `export` syntax in `.js` files
+
+Yes, we heard [you](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md). And [you](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054). And [you](https://twitter.com/maybekatz/status/1062473765865512961). You can now use `import` and `export` syntax in `.js` files.
+
+The `.mjs` extension is still supported, and still always explicitly means that its file uses the Module parse goal (and therefore is an ES module). We also created a new `.cjs` file extension, to explicitly signify that a file should be treated as CommonJS. (CommonJS is the other module system that Node.js supports, with `require` and `module.exports`.) These two extensions allow individual files to define how they should be loaded, as ES modules or as CommonJS.
+
+As it turns out, a lot of people didn’t like needing to use a new file extension for JavaScript. Browsers don’t require it, tools that build and process JavaScript have issues with it, and languages that transpile into JavaScript such as TypeScript and CoffeeScript don’t necessarily know when to save their output as `.js` or as `.mjs`. So while `.mjs` and `.cjs` have use cases that only they can solve (ES module and CommonJS files side-by-side in the same folder, loose JavaScript files outside of any package) the modules group searched for solutions other than `.mjs` to let Node.js know when to interpret a file as an ES module.
+
+We came up with two things: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
+
+### `package.json` `"type"` field
+
+Add `"type": "module"` to the `package.json` for your project, and Node will treat all `.js` files in your project as ES modules.
+
+If some of your project’s files use CommonJS and you can’t convert your entire project all at once, you can either rename those files to use the `.cjs` extension or put them in a subfolder containing a `package.json` with `{ "type": "commonjs" }`, under which all `.js` files are treated as CommonJS.
+
+For any file that Node.js tries to load, it will look for a `package.json` in that file’s folder, then that file’s parent folder and so on upwards until it reaches the root of the volume. This is similar to [how Babel searches for `.babelrc` files](https://babeljs.io/docs/en/config-files#file-relative-configuration). This new approach allows Node.js to use `package.json` for package-level metadata and configuration, similar to how it is already used by Babel and other tools.
+
+### `--type` flag
+
+Use `--type=module`, or the shorthand `-m`, to run a `.js` file as an ES module.
+
+When running a file, e.g. `node file.js`, Node follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--type` flag. The `--type` flag can be `--type=module` (or `-m`) or `--type=commonjs`. You can also set this flag in `NODE_OPTIONS` if you’d like to change how Node behaves systemwide.
+
+This flag provides a way to support ES module syntax for input via `--eval`, `--print` or `STDIN`.
+
+## Mandatory file extensions
+
+In the new `--experimental-modules`, file extensions are mandatory in `import` statements: `import './file.js'`, not `import './file'`. However, the CommonJS-style automatic extension resolution behavior (`'./file'`) can be enabled via a new flag, `--es-module-specifier-resolution=node`. (Its inverse, the default, is `--es-module-specifier-resolution=explicit`.) Package names are still just package names, e.g. `import fs from 'fs'`.
+
+This change isn’t because we’re trying to annoy an entirely new constituency now that `.mjs` is no longer required. We recognize that there are years’ worth of JavaScript out there written in the extensionless style, and this will feel like a huge breaking change for all that code. That’s why we’re providing the `--es-module-specifier-resolution=node` flag, and this is also subject to change before `--experimental-modules` itself ships unflagged.
+
+We’re making this change to align with browsers, where [extensions are required](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
+
+Also, [import maps may bring support for automatic extension resolution to browsers](https://github.com/WICG/import-maps#extension-less-imports). It would be premature for Node to implement its own solution to supporting extensionless specifiers while efforts are underway to provide a cross-platform standard. Again, this is subject to change.
+
+## `module.createRequireFromPath`
+
+The “CommonJS globals” `require`, `exports`, `module.exports`, `__filename`, `__dirname` are undefined in ES modules. However, [`module.createRequireFromPath()`](https://nodejs.org/api/modules.html#modules_module_createrequirefrompath_filename) can be used to create a CommonJS `require` function to be used in an ES module context.
+
+## `import` for JavaScript only
+
+The previous `--experimental-modules` allowed `import` statements of JSON and native modules. This has been removed; you may use `module.createRequireFromPath()` for these.
+
+There is ongoing work in the standards space to cover JSON and WASM and other future potential module types. Node.js will add support for these in compliant ways when the standard is finalized.
+
+## ES module code in packages
+
+_This is a work in progress and subject to change._ You can create a package with ES module sources by using the `package.json` `"main"` field to point to an ES module package entry point. Node will know to load it as an ES module if the file ends in `.mjs` or if the `package.json` also contains `"type": "module"`.
+
+Currently it is not possible to create a package that is usable both via `require` (as CommonJS) and via `import` (as an ES module). There are efforts underway to address this, and may involve changes to the above (especially concerning `"main"`). Please do not publish any ES module packages intended for use by Node.js until this is resolved.
+
+## Coming soon
+
+All of the above is shipping as part of `--experimental-modules` in Node.js 12. On our [road map](https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md) for improvements before the `--experimental-modules` flag is hopefully dropped in October 2019, when Node.js 12 reaches LTS status:
+
+- **Better loaders.** The current loaders code is a holdover from the previous `--experimental-modules` and doesn’t fully integrate with the new system. There is much work to be done here.
+
+- **Dual CommonJS/ES module packages.** We want to provide a standard way for package authors to publish a package that can be both `require`d into CommonJS or `import`ed into an ES module.
+
+- **Easier `require`.** Using `module.createRequireFromPath()` involves a lot of boilerplate. We hope to provide a simpler way to use `require` in ES module code.
+
+- **Package path maps.** Along the lines of the browser [import maps proposal](https://github.com/WICG/import-maps), we would like to support paths to files within packages. This would allow things like `import sdk from 'some-service/sdk'` to have `'some-service/sdk'` map to something like `./src/sdk/index.mjs`.
+
+- **Automatic entry point module type detection.** This would provide a way for running `.js` files as either CommonJS or ES modules based on whether `import` or `export` statements appear in the source code of the file.
+
+That’s it! We hope you enjoy this new `--experimental-modules`, and we look forward to hearing your feedback. The modules team’s work is public at https://github.com/nodejs/modules.

From 6dee5cd176612f56f9ca9b07682cceea0bd632c9 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Wed, 13 Mar 2019 09:11:10 -0700
Subject: [PATCH 2/9] Revisions per feedback

---
 doc/announcement.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index bcc3d92..319d343 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -2,11 +2,11 @@
 
 Back in 2017, Node.js 8.9.0 shipped experimental support for [ECMAScript modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/), known for their `import` and `export` statements. This support was behind the flag `--experimental-modules`.
 
-A lot has happened since then. All major browsers [now support](https://caniuse.com/#feat=es6-module) ECMAScript modules (ES modules) via `<script type="module">`. Various projects have sprung up to make NPM packages with ES module sources available for use in browsers via `<script type="module">`. Support for [import maps](https://github.com/WICG/import-maps), which bring to browsers Node-style package names in `import` statements, [is coming to Chrome](https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/qYeQFqgFOyA/rXJapjMaEAAJ).
+A lot has happened since then. All major browsers [now support](https://caniuse.com/#feat=es6-module) ECMAScript modules (ES modules) via `<script type="module">`. Various projects have sprung up to make npm packages with ES module sources available for use in browsers via `<script type="module">`. Support for [import maps](https://github.com/WICG/import-maps), which bring to browsers Node-style package names in `import` statements, [is coming to Chrome](https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/qYeQFqgFOyA/rXJapjMaEAAJ).
 
-All this progress toward adoption of ES modules has increased the urgency for Node.js to ship its support for ES modules. Especially now that there are other runtimes and environments where ES modules are in use, it’s more important than ever that Node.js join the JavaScript standard.
+All this progress toward adoption of ES modules has increased the urgency for Node.js to ship its support for ES modules. Now that there are other runtimes and environments where ES modules are in use, it’s more important than ever that Node.js support the JavaScript standard.
 
-Yet Node’s initial ES modules support has remained in an experimental state, largely due to strong pushback from the community to several decisions that were made in its design. In response, the [Modules Team](https://github.com/nodejs/modules) was formed to take a fresh look at implementing support for ES modules in Node.js. This has led to a [new implementation](https://github.com/nodejs/ecmascript-modules) for supporting ES modules, that we are pleased to announce will ship as part of Node.js 12. It will replace the old `--experimental-modules` implementation, behind the same flag. We hope that this new implementation addresses many of the community’s concerns, and can ship as part of Node.js proper, without a flag, before Node.js 12 reaches [LTS status](https://nodejs.org/en/about/releases/) in October 2019.
+Node’s initial ES modules support remained in an experimental state in order to allow the community time to provide feedback on that design. The [Modules Team](https://github.com/nodejs/modules) was formed to act on this feedback and ship first-class support for ES modules in Node.js. This has led to a [new implementation](https://github.com/nodejs/ecmascript-modules) for supporting ES modules, that we are pleased to announce will ship as part of Node.js 12. It will replace the old `--experimental-modules` implementation, behind the same flag. We hope that this new implementation addresses many of the community’s concerns, and can ship as part of Node.js proper, without a flag, before Node.js 12 reaches [LTS status](https://nodejs.org/en/about/releases/) in October 2019.
 
 ## What’s in `--experimental-modules`
 
@@ -14,18 +14,20 @@ Like the previous version, this new `--experimental-modules` adds support to Nod
 
 - [ES2015 `import` statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) can reference JavaScript files that are themselves written using ES module syntax. Files can be referenced as relative URLs (`'./file.mjs'`), absolute `file://` URLs (`'file:///opt/app/file.mjs'`), package names (`'es-module-package'`) or paths within packages (`'es-module-package/lib/file.mjs'`).
 
-- `import` statements that reference ES module files can specify both the default export (`import _ from 'es-module-package'`) or named exports (`import { shuffle } from 'es-module-package'`). All Node.js built-in packages like `fs` and `path` support both default and named exports.
+- `import` statements that reference ES module files can specify both the default export (`import _ from 'es-module-package'`), named exports (`import { shuffle } from 'es-module-package'`) and namespace exports (`import * as fs from 'fs'`). All Node.js built-in packages like `fs` and `path` support all three types of exports.
 
 - `import` statements that reference CommonJS files (all current JavaScript code written for Node.js, [using `require` and `module.exports`](https://nodejs.org/api/modules.html)) can use the CommonJS default export (`import _ from 'commonjs-package'`) only. _This is a work in progress and may change in the future._
 
 - [`export` statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) in ES module files can specify both default and named exports for `import` statements to reference.
 
-- Dynamic `import()` expressions can be used to import ES modules into either CommonJS or ES module files. Note that `import()` returns a promise.
+- Dynamic `import()` expressions can be used to import ES modules from either CommonJS or ES module files. Note that `import()` returns a promise.
 
 - `import.meta.url` provides the `file://` URL of the current ES module file.
 
 - Node.js can be run with an ES module file as a program’s initial entry point.
 
+- Files loaded as ES modules are loaded in strict mode, which in CommonJS requires adding `'use strict';` to the top of every file.
+
 - Loaders can be written to modify Node’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
 
 So if that’s what’s carried over from the previous implementation, what’s new?
@@ -36,8 +38,6 @@ Yes, we heard [you](https://github.com/dherman/defense-of-dot-js/blob/master/pro
 
 The `.mjs` extension is still supported, and still always explicitly means that its file uses the Module parse goal (and therefore is an ES module). We also created a new `.cjs` file extension, to explicitly signify that a file should be treated as CommonJS. (CommonJS is the other module system that Node.js supports, with `require` and `module.exports`.) These two extensions allow individual files to define how they should be loaded, as ES modules or as CommonJS.
 
-As it turns out, a lot of people didn’t like needing to use a new file extension for JavaScript. Browsers don’t require it, tools that build and process JavaScript have issues with it, and languages that transpile into JavaScript such as TypeScript and CoffeeScript don’t necessarily know when to save their output as `.js` or as `.mjs`. So while `.mjs` and `.cjs` have use cases that only they can solve (ES module and CommonJS files side-by-side in the same folder, loose JavaScript files outside of any package) the modules group searched for solutions other than `.mjs` to let Node.js know when to interpret a file as an ES module.
-
 We came up with two things: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
 
 ### `package.json` `"type"` field
@@ -56,19 +56,19 @@ When running a file, e.g. `node file.js`, Node follows an algorithm to determine
 
 This flag provides a way to support ES module syntax for input via `--eval`, `--print` or `STDIN`.
 
-## Mandatory file extensions
+## Explicit filenames
 
-In the new `--experimental-modules`, file extensions are mandatory in `import` statements: `import './file.js'`, not `import './file'`. However, the CommonJS-style automatic extension resolution behavior (`'./file'`) can be enabled via a new flag, `--es-module-specifier-resolution=node`. (Its inverse, the default, is `--es-module-specifier-resolution=explicit`.) Package names are still just package names, e.g. `import fs from 'fs'`.
+By default in the new `--experimental-modules`, file extensions are mandatory in `import` statements: `import './file.js'`, not `import './file'`. However, the CommonJS-style automatic extension resolution behavior (`'./file'`) can be enabled via a new flag, `--es-module-specifier-resolution=node`. (Its inverse, the default, is `--es-module-specifier-resolution=explicit`.) Package names are still just package names, e.g. `import fs from 'fs'`.
 
-This change isn’t because we’re trying to annoy an entirely new constituency now that `.mjs` is no longer required. We recognize that there are years’ worth of JavaScript out there written in the extensionless style, and this will feel like a huge breaking change for all that code. That’s why we’re providing the `--es-module-specifier-resolution=node` flag, and this is also subject to change before `--experimental-modules` itself ships unflagged.
+We’re providing the `--es-module-specifier-resolution=node` flag to opt in to cjs-style extension and `index` resolution. We’ve turned it off by default to collect feedback on how users feel about using fully specified paths before we unflag the `--experimental-modules` implementation. You can find our discussion on the topic [here](https://github.com/nodejs/modules/issues/268).
 
 We’re making this change to align with browsers, where [extensions are required](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
 
-Also, [import maps may bring support for automatic extension resolution to browsers](https://github.com/WICG/import-maps#extension-less-imports). It would be premature for Node to implement its own solution to supporting extensionless specifiers while efforts are underway to provide a cross-platform standard. Again, this is subject to change.
+Also, [import maps may bring support for automatic extension resolution to browsers](https://github.com/WICG/import-maps#extension-less-imports). Should that proposal be accepted, Node is interested in supporting extensionless specifiers in a cross-platform compatible way.
 
 ## `module.createRequireFromPath`
 
-The “CommonJS globals” `require`, `exports`, `module.exports`, `__filename`, `__dirname` are undefined in ES modules. However, [`module.createRequireFromPath()`](https://nodejs.org/api/modules.html#modules_module_createrequirefrompath_filename) can be used to create a CommonJS `require` function to be used in an ES module context.
+The “CommonJS globals” `require`, `exports`, `module.exports`, `__filename`, `__dirname` are not defined in ES modules. However, [`module.createRequireFromPath()`](https://nodejs.org/api/modules.html#modules_module_createrequirefrompath_filename) can be used to create a CommonJS `require` function to be used in an ES module context.
 
 ## `import` for JavaScript only
 

From f57ac38fef65447f4cc2a6ac383f9c2b7200534f Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Fri, 15 Mar 2019 22:55:18 -0700
Subject: [PATCH 3/9] Revisions per feedback

---
 doc/announcement.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index 319d343..bcd6a86 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -54,7 +54,7 @@ Use `--type=module`, or the shorthand `-m`, to run a `.js` file as an ES module.
 
 When running a file, e.g. `node file.js`, Node follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--type` flag. The `--type` flag can be `--type=module` (or `-m`) or `--type=commonjs`. You can also set this flag in `NODE_OPTIONS` if you’d like to change how Node behaves systemwide.
 
-This flag provides a way to support ES module syntax for input via `--eval`, `--print` or `STDIN`.
+This flag provides a way to support ES module syntax for input via `--eval`, `--print`, or `STDIN`.
 
 ## Explicit filenames
 
@@ -64,7 +64,7 @@ We’re providing the `--es-module-specifier-resolution=node` flag to opt in to
 
 We’re making this change to align with browsers, where [extensions are required](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
 
-Also, [import maps may bring support for automatic extension resolution to browsers](https://github.com/WICG/import-maps#extension-less-imports). Should that proposal be accepted, Node is interested in supporting extensionless specifiers in a cross-platform compatible way.
+Also, [import maps may bring support for similar functionality to browsers](https://github.com/WICG/import-maps#extension-less-imports). Should that proposal be accepted, Node is interested in supporting extensionless specifiers in a cross-platform compatible way.
 
 ## `module.createRequireFromPath`
 
@@ -74,7 +74,9 @@ The “CommonJS globals” `require`, `exports`, `module.exports`, `__filename`,
 
 The previous `--experimental-modules` allowed `import` statements of JSON and native modules. This has been removed; you may use `module.createRequireFromPath()` for these.
 
-There is ongoing work in the standards space to cover JSON and WASM and other future potential module types. Node.js will add support for these in compliant ways when the standard is finalized.
+A separate flag `--experimental-json-modules` enables experimental support for `import` of JSON files. There is [work in progress](https://github.com/whatwg/html/issues/4315) for standardizing this feature with browsers, and Node hopes to align our support with the eventual standard.
+
+There is also ongoing work to cover WASM and other future potential module types. Node.js will add support for these in spec-compliant ways over time.
 
 ## ES module code in packages
 
@@ -82,9 +84,9 @@ _This is a work in progress and subject to change._ You can create a package wit
 
 Currently it is not possible to create a package that is usable both via `require` (as CommonJS) and via `import` (as an ES module). There are efforts underway to address this, and may involve changes to the above (especially concerning `"main"`). Please do not publish any ES module packages intended for use by Node.js until this is resolved.
 
-## Coming soon
+## Works in progress
 
-All of the above is shipping as part of `--experimental-modules` in Node.js 12. On our [road map](https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md) for improvements before the `--experimental-modules` flag is hopefully dropped in October 2019, when Node.js 12 reaches LTS status:
+All of the above is shipping as part of `--experimental-modules` in Node.js 12. On our [road map](https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md) for potential improvements before the `--experimental-modules` flag is hopefully dropped in October 2019, when Node.js 12 reaches LTS status:
 
 - **Better loaders.** The current loaders code is a holdover from the previous `--experimental-modules` and doesn’t fully integrate with the new system. There is much work to be done here.
 

From f9bda3bfb36dc45a2a1893ac7ab17d0bb5160a19 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Fri, 15 Mar 2019 23:29:51 -0700
Subject: [PATCH 4/9] Revisions per feedback

---
 doc/announcement.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index bcd6a86..517a0a0 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -62,7 +62,7 @@ By default in the new `--experimental-modules`, file extensions are mandatory in
 
 We’re providing the `--es-module-specifier-resolution=node` flag to opt in to cjs-style extension and `index` resolution. We’ve turned it off by default to collect feedback on how users feel about using fully specified paths before we unflag the `--experimental-modules` implementation. You can find our discussion on the topic [here](https://github.com/nodejs/modules/issues/268).
 
-We’re making this change to align with browsers, where [extensions are required](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
+We’re making this change to align with browsers, where [file extensions are generally always needed in `import` statements](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
 
 Also, [import maps may bring support for similar functionality to browsers](https://github.com/WICG/import-maps#extension-less-imports). Should that proposal be accepted, Node is interested in supporting extensionless specifiers in a cross-platform compatible way.
 

From e6398df58f7b016aa2b2c0b2640635424f632701 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Sat, 16 Mar 2019 02:05:59 -0700
Subject: [PATCH 5/9] Trim references to import maps

---
 doc/announcement.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index 517a0a0..2b7dbaa 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -62,9 +62,7 @@ By default in the new `--experimental-modules`, file extensions are mandatory in
 
 We’re providing the `--es-module-specifier-resolution=node` flag to opt in to cjs-style extension and `index` resolution. We’ve turned it off by default to collect feedback on how users feel about using fully specified paths before we unflag the `--experimental-modules` implementation. You can find our discussion on the topic [here](https://github.com/nodejs/modules/issues/268).
 
-We’re making this change to align with browsers, where [file extensions are generally always needed in `import` statements](https://github.com/WICG/import-maps#extension-less-imports). Part of the reason for Node.js to support ES modules in the first place is because ES modules are the standard, and the point of aligning to standards is to increase compatibility and interoperability between systems. In this case, Node.js supporting ES modules means that more JavaScript code will be capable of running in either Node or in browsers, without requiring some kind of translation process to make the code compatible with one or the other. Of course, it will always remain possible for users to write code that can’t function cross-platform (JavaScript referencing `window`, or importing `fs`, for example) but by aligning as much as we can, we encourage code to be cross-platform by default.
-
-Also, [import maps may bring support for similar functionality to browsers](https://github.com/WICG/import-maps#extension-less-imports). Should that proposal be accepted, Node is interested in supporting extensionless specifiers in a cross-platform compatible way.
+Since explicit file extensions are usually required on the Web, we hope that aligning with that style encourages code to be cross-platform by default.
 
 ## `module.createRequireFromPath`
 
@@ -94,7 +92,7 @@ All of the above is shipping as part of `--experimental-modules` in Node.js 12.
 
 - **Easier `require`.** Using `module.createRequireFromPath()` involves a lot of boilerplate. We hope to provide a simpler way to use `require` in ES module code.
 
-- **Package path maps.** Along the lines of the browser [import maps proposal](https://github.com/WICG/import-maps), we would like to support paths to files within packages. This would allow things like `import sdk from 'some-service/sdk'` to have `'some-service/sdk'` map to something like `./src/sdk/index.mjs`.
+- **Package path maps.** We would like to support paths to files within packages. This would allow things like `import sdk from 'some-service/sdk'` to have `'some-service/sdk'` map to something like `./src/sdk/public-api.mjs`.
 
 - **Automatic entry point module type detection.** This would provide a way for running `.js` files as either CommonJS or ES modules based on whether `import` or `export` statements appear in the source code of the file.
 

From 6963b969e4fd622168677f49edbba2044972ca4a Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Sat, 16 Mar 2019 04:12:20 -0700
Subject: [PATCH 6/9] Rework the ESM-in-.js section

---
 doc/announcement.md | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index 2b7dbaa..ac8246d 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -24,21 +24,21 @@ Like the previous version, this new `--experimental-modules` adds support to Nod
 
 - `import.meta.url` provides the `file://` URL of the current ES module file.
 
+- Loaders can be written to modify Node’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
+
 - Node.js can be run with an ES module file as a program’s initial entry point.
 
 - Files loaded as ES modules are loaded in strict mode, which in CommonJS requires adding `'use strict';` to the top of every file.
 
-- Loaders can be written to modify Node’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
+- Files ending in `.mjs` are explicitly treated as ES modules in `import` statements and when run via the `node` command.
 
-So if that’s what’s carried over from the previous implementation, what’s new?
+And the new version of `--experimental-modules` adds:
 
 ## `import` and `export` syntax in `.js` files
 
-Yes, we heard [you](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md). And [you](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054). And [you](https://twitter.com/maybekatz/status/1062473765865512961). You can now use `import` and `export` syntax in `.js` files.
+We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node needs to provide a way to use `import` and `export` syntax in `.js` files.
 
-The `.mjs` extension is still supported, and still always explicitly means that its file uses the Module parse goal (and therefore is an ES module). We also created a new `.cjs` file extension, to explicitly signify that a file should be treated as CommonJS. (CommonJS is the other module system that Node.js supports, with `require` and `module.exports`.) These two extensions allow individual files to define how they should be loaded, as ES modules or as CommonJS.
-
-We came up with two things: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
+The new `--experimental-modules` provides two ways: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
 
 ### `package.json` `"type"` field
 
@@ -56,6 +56,10 @@ When running a file, e.g. `node file.js`, Node follows an algorithm to determine
 
 This flag provides a way to support ES module syntax for input via `--eval`, `--print`, or `STDIN`.
 
+## `.cjs` extension
+
+Just as the `.mjs` file extension explicitly signifies that a file should be treated as an ES module, the new `.cjs` file extension explicitly signifies that a file should be treated as CommonJS. (CommonJS is the other module system that Node.js supports, with `require` and `module.exports`.) The `.cjs` extension provides a way to save CommonJS files in a project where both `.mjs` and `.js` files are treated as ES modules.
+
 ## Explicit filenames
 
 By default in the new `--experimental-modules`, file extensions are mandatory in `import` statements: `import './file.js'`, not `import './file'`. However, the CommonJS-style automatic extension resolution behavior (`'./file'`) can be enabled via a new flag, `--es-module-specifier-resolution=node`. (Its inverse, the default, is `--es-module-specifier-resolution=explicit`.) Package names are still just package names, e.g. `import fs from 'fs'`.

From 1116d7d7c359cbaa0f3b3e1a504c8c14acfc073d Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Sat, 16 Mar 2019 05:00:38 -0700
Subject: [PATCH 7/9] Notes from feedback

---
 doc/announcement.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index ac8246d..65a17b9 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -2,11 +2,11 @@
 
 Back in 2017, Node.js 8.9.0 shipped experimental support for [ECMAScript modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/), known for their `import` and `export` statements. This support was behind the flag `--experimental-modules`.
 
-A lot has happened since then. All major browsers [now support](https://caniuse.com/#feat=es6-module) ECMAScript modules (ES modules) via `<script type="module">`. Various projects have sprung up to make npm packages with ES module sources available for use in browsers via `<script type="module">`. Support for [import maps](https://github.com/WICG/import-maps), which bring to browsers Node-style package names in `import` statements, [is coming to Chrome](https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/qYeQFqgFOyA/rXJapjMaEAAJ).
+A lot has happened since then. All major browsers [now support](https://caniuse.com/#feat=es6-module) ECMAScript modules (ES modules) via `<script type="module">`. Various projects have sprung up to make npm packages with ES module sources available for use in browsers via `<script type="module">`. Support for [import maps](https://github.com/WICG/import-maps), which bring to browsers Node.js-style package names in `import` statements, [is coming to Chrome](https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/qYeQFqgFOyA/rXJapjMaEAAJ).
 
-All this progress toward adoption of ES modules has increased the urgency for Node.js to ship its support for ES modules. Now that there are other runtimes and environments where ES modules are in use, it’s more important than ever that Node.js support the JavaScript standard.
+All this progress toward adoption of ES modules has increased the urgency for Node.js to ship its support for ES modules. Now that there are other runtimes and environments where ES modules are in use, it’s more important than ever that Node.js support this JavaScript standard.
 
-Node’s initial ES modules support remained in an experimental state in order to allow the community time to provide feedback on that design. The [Modules Team](https://github.com/nodejs/modules) was formed to act on this feedback and ship first-class support for ES modules in Node.js. This has led to a [new implementation](https://github.com/nodejs/ecmascript-modules) for supporting ES modules, that we are pleased to announce will ship as part of Node.js 12. It will replace the old `--experimental-modules` implementation, behind the same flag. We hope that this new implementation addresses many of the community’s concerns, and can ship as part of Node.js proper, without a flag, before Node.js 12 reaches [LTS status](https://nodejs.org/en/about/releases/) in October 2019.
+Node.js’s initial ES modules support remained in an experimental state in order to allow the community time to provide feedback on that design. The [Modules Team](https://github.com/nodejs/modules) was formed to act on this feedback and ship first-class support for ES modules in Node.js. This has led to a [new implementation](https://github.com/nodejs/ecmascript-modules) for supporting ES modules, that we are pleased to announce will ship as part of Node.js 12. It will replace the old `--experimental-modules` implementation, behind the same flag. We hope that this new implementation addresses many of the community’s concerns, and can ship as part of Node.js proper, without a flag, before Node.js 12 reaches [LTS status](https://nodejs.org/en/about/releases/) in October 2019.
 
 ## What’s in `--experimental-modules`
 
@@ -24,7 +24,7 @@ Like the previous version, this new `--experimental-modules` adds support to Nod
 
 - `import.meta.url` provides the `file://` URL of the current ES module file.
 
-- Loaders can be written to modify Node’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
+- Loaders can be written to modify Node.js’s runtime behavior with respect to ES modules. _This is still very much a work in progress._
 
 - Node.js can be run with an ES module file as a program’s initial entry point.
 
@@ -36,13 +36,13 @@ And the new version of `--experimental-modules` adds:
 
 ## `import` and `export` syntax in `.js` files
 
-We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node needs to provide a way to use `import` and `export` syntax in `.js` files.
+We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.
 
 The new `--experimental-modules` provides two ways: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
 
 ### `package.json` `"type"` field
 
-Add `"type": "module"` to the `package.json` for your project, and Node will treat all `.js` files in your project as ES modules.
+Add `"type": "module"` to the `package.json` for your project, and Node.js will treat all `.js` files in your project as ES modules.
 
 If some of your project’s files use CommonJS and you can’t convert your entire project all at once, you can either rename those files to use the `.cjs` extension or put them in a subfolder containing a `package.json` with `{ "type": "commonjs" }`, under which all `.js` files are treated as CommonJS.
 
@@ -52,7 +52,7 @@ For any file that Node.js tries to load, it will look for a `package.json` in th
 
 Use `--type=module`, or the shorthand `-m`, to run a `.js` file as an ES module.
 
-When running a file, e.g. `node file.js`, Node follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--type` flag. The `--type` flag can be `--type=module` (or `-m`) or `--type=commonjs`. You can also set this flag in `NODE_OPTIONS` if you’d like to change how Node behaves systemwide.
+When running a file, e.g. `node --experimental-modules --type=module main.js`, Node.js follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--type` flag. The `--type` flag can be `--type=module` (or `-m`) or `--type=commonjs`. You can also set this flag in `NODE_OPTIONS` if you’d like to change how Node.js behaves systemwide.
 
 This flag provides a way to support ES module syntax for input via `--eval`, `--print`, or `STDIN`.
 
@@ -76,13 +76,13 @@ The “CommonJS globals” `require`, `exports`, `module.exports`, `__filename`,
 
 The previous `--experimental-modules` allowed `import` statements of JSON and native modules. This has been removed; you may use `module.createRequireFromPath()` for these.
 
-A separate flag `--experimental-json-modules` enables experimental support for `import` of JSON files. There is [work in progress](https://github.com/whatwg/html/issues/4315) for standardizing this feature with browsers, and Node hopes to align our support with the eventual standard.
+A separate flag `--experimental-json-modules` enables experimental support for `import` of JSON files. There is [work in progress](https://github.com/whatwg/html/issues/4315) for standardizing this feature with browsers, and Node.js hopes to align our support with the eventual standard.
 
 There is also ongoing work to cover WASM and other future potential module types. Node.js will add support for these in spec-compliant ways over time.
 
 ## ES module code in packages
 
-_This is a work in progress and subject to change._ You can create a package with ES module sources by using the `package.json` `"main"` field to point to an ES module package entry point. Node will know to load it as an ES module if the file ends in `.mjs` or if the `package.json` also contains `"type": "module"`.
+_This is a work in progress and subject to change._ You can create a package with ES module sources by using the `package.json` `"main"` field to point to an ES module package entry point. Node.js will know to load it as an ES module if the file ends in `.mjs` or if the `package.json` also contains `"type": "module"`.
 
 Currently it is not possible to create a package that is usable both via `require` (as CommonJS) and via `import` (as an ES module). There are efforts underway to address this, and may involve changes to the above (especially concerning `"main"`). Please do not publish any ES module packages intended for use by Node.js until this is resolved.
 
@@ -90,7 +90,7 @@ Currently it is not possible to create a package that is usable both via `requir
 
 All of the above is shipping as part of `--experimental-modules` in Node.js 12. On our [road map](https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md) for potential improvements before the `--experimental-modules` flag is hopefully dropped in October 2019, when Node.js 12 reaches LTS status:
 
-- **Better loaders.** The current loaders code is a holdover from the previous `--experimental-modules` and doesn’t fully integrate with the new system. There is much work to be done here.
+**Loaders features.** Loaders are being further developed to support process isolation, multiple loaders, and multi-Realm support with lower-level hooks. The `--loader` API will still change considerably before this is unflagged.
 
 - **Dual CommonJS/ES module packages.** We want to provide a standard way for package authors to publish a package that can be both `require`d into CommonJS or `import`ed into an ES module.
 

From 4be23c8e5760c18096ec43a75b878929916769bc Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webmaster@geoffreybooth.com>
Date: Sat, 16 Mar 2019 13:51:14 -0700
Subject: [PATCH 8/9] Add detail about dual packages and "module"

---
 doc/announcement.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index 65a17b9..ca6c7de 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -84,7 +84,7 @@ There is also ongoing work to cover WASM and other future potential module types
 
 _This is a work in progress and subject to change._ You can create a package with ES module sources by using the `package.json` `"main"` field to point to an ES module package entry point. Node.js will know to load it as an ES module if the file ends in `.mjs` or if the `package.json` also contains `"type": "module"`.
 
-Currently it is not possible to create a package that is usable both via `require` (as CommonJS) and via `import` (as an ES module). There are efforts underway to address this, and may involve changes to the above (especially concerning `"main"`). Please do not publish any ES module packages intended for use by Node.js until this is resolved.
+Currently it is not possible to create a package that can be used via both `require('pkg')` and `import 'pkg'`. There are efforts underway to address this, and may involve changes to the above. In particular, Node.js might choose a field other than `"main"` to define a package’s ES module entry point. While we are aware that the community has embraced the `"module"` field, it is unlikely that Node.js will adopt that field as many of the packages published using `"module"` include ES module JavaScript that may not evaluate in Node.js (because extensions are left off of filenames, or the code includes `require` statements, etc.). Please do not publish any ES module packages intended for use by Node.js until this is resolved.
 
 ## Works in progress
 

From 10e4d214d3a14e2b823004376388bc2c6e9aa6c4 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <GeoffreyBooth@users.noreply.github.com>
Date: Mon, 25 Mar 2019 14:33:49 -0700
Subject: [PATCH 9/9] Nit: capitalization

---
 doc/announcement.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/announcement.md b/doc/announcement.md
index ca6c7de..7aa7866 100644
--- a/doc/announcement.md
+++ b/doc/announcement.md
@@ -1,4 +1,4 @@
-# Announcing a New `--experimental-modules`
+# Announcing a new `--experimental-modules`
 
 Back in 2017, Node.js 8.9.0 shipped experimental support for [ECMAScript modules](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/), known for their `import` and `export` statements. This support was behind the flag `--experimental-modules`.