From 2bec61e1f86b067e35859c39f344babf7c1e9f7f Mon Sep 17 00:00:00 2001 From: lulzmachine Date: Thu, 12 Mar 2020 21:32:48 +0100 Subject: [PATCH 1/2] Update esm.md Update es module documentation in accordance to https://github.com/nodejs/node/issues/31710 by providing a gotcha for windows users --- doc/api/esm.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doc/api/esm.md b/doc/api/esm.md index 60c0a6f286c0ec..ef67c2049f5f5c 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -801,6 +801,18 @@ property: ## Differences Between ES Modules and CommonJS +### Absolute file paths don't work on Windows + +Note that `import` accepts _absolute specifiers_. These are similar to _absolute paths_ on linux and MacOS, and therefore they are also accepted. But on Windows, importing an _absolute path_ to a file will not work. Therefore, to ensure cross platform compatibility, be sure to turn your file paths into urls, like so: + +``` +import { pathToFileURL } from 'url'; + +const fileUrl = pathToFileURL(...your path here...).href; + +await import(fileUrl) +``` + ### Mandatory file extensions A file extension must be provided when using the `import` keyword. Directory From ea679b765a8de54fc0c73b08a9db053261c308b5 Mon Sep 17 00:00:00 2001 From: Jon Date: Sun, 15 Mar 2020 16:57:44 +0100 Subject: [PATCH 2/2] esm: Update documentation with windows gotcha Explains that absolute specifiers and absolute paths are not the same, and mentions what to do about it. Refs: https://github.com/nodejs/node/issues/31710 --- doc/api/esm.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index ef67c2049f5f5c..88b4f01f60deee 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -803,14 +803,18 @@ property: ### Absolute file paths don't work on Windows -Note that `import` accepts _absolute specifiers_. These are similar to _absolute paths_ on linux and MacOS, and therefore they are also accepted. But on Windows, importing an _absolute path_ to a file will not work. Therefore, to ensure cross platform compatibility, be sure to turn your file paths into urls, like so: +`import` accepts _absolute specifiers_. These are similar to _absolute paths_ +on linux and MacOS, and therefore they are also accepted. +But on Windows, importing an _absolute path_ to a file will not work. +To ensure cross platform compatibility, file paths should be converted into +URLs. -``` +```js import { pathToFileURL } from 'url'; -const fileUrl = pathToFileURL(...your path here...).href; +const fileUrl = pathToFileURL('c:\\path\\to\\file.js').href; -await import(fileUrl) +await import(fileUrl); ``` ### Mandatory file extensions