-
Notifications
You must be signed in to change notification settings - Fork 322
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Clarify recommendations regarding .mjs #228
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -126,13 +126,16 @@ Another difference relates to the `async` attribute, which causes the script to | |
|
||
You may have noticed we’re using the `.mjs` file extension for modules. On the Web, the file extension doesn’t really matter, as long as the file is served with [the JavaScript MIME type `text/javascript`](https://html.spec.whatwg.org/multipage/scripting.html#scriptingLanguages:javascript-mime-type). The browser knows it’s a module because of the `type` attribute on the script element. | ||
|
||
Still, we recommend using the `.mjs` extension for modules, for two reasons: | ||
In production, you should name your files with an `.mjs` extension only if you are sure that they will be served with the required `Content-Type: text/javascript` header. If your host lacks such support, or if you are publishing open source JavaScript for public use by others, it’s safer to use the `.js` extension. | ||
|
||
1. During development, it makes it crystal clear that the file is a module as opposed to a regular script. (It’s not always possible to tell just by looking at the code.) As mentioned before, modules are treated differently than regular scripts, so the difference is hugely important! | ||
1. It’s consistent with Node.js, where [the experimental modules implementation](https://nodejs.org/api/esm.html) only supports files with the `.mjs` extension by default. | ||
GeoffreyBooth marked this conversation as resolved.
Show resolved
Hide resolved
GeoffreyBooth marked this conversation as resolved.
Show resolved
Hide resolved
|
||
During development, we recommend using the `.mjs` extension for modules, for two reasons: | ||
|
||
1. The `.mjs` extension makes it crystal clear to you and anyone else looking at your project that the file is a module as opposed to a regular script. (It’s not always possible to tell just by looking at the code.) As mentioned before, modules are treated differently than regular scripts, so the difference is hugely important! | ||
|
||
1. It ensures that your file is parsed as a module by runtimes such as [Node.js](https://nodejs.org/api/esm.html#esm_enabling) and [`d8`](/docs/d8), and build tools such as [Babel](https://babeljs.io/docs/en/options#sourcetype). While these environments and tools each have proprietary ways via configuration to interpret `.js` files as modules, the `.mjs` extension is the cross-compatible way to ensure that files are treated as modules. | ||
|
||
:::note | ||
**Note:** To deploy `.mjs` on the web, your web server needs to be configured to serve files with this extension using the appropriate `Content-Type: text/javascript` header, as mentioned above. Additionally, you may want to configure your editor to treat `.mjs` files as `.js` files to get syntax highlighting. Most modern editors already do this by default. | ||
GeoffreyBooth marked this conversation as resolved.
Show resolved
Hide resolved
|
||
**Note:** You may want to configure your editor to treat `.mjs` files as `.js` files to get syntax highlighting. Most modern editors already do this by default. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I’ve revised this to be much closer to your original text. I still think it weakens the article to include a discussion of non-Web platforms, but if you want that included, I think this language is a fairer and stronger explanation of The previous previous text (“It’s consistent with Node.js, where the experimental modules implementation only supports files with the |
||
::: | ||
|
||
### Module specifiers { #specifiers } | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems like we should just keep this, and update the link to https://nodejs.org/api/esm.html#esm_enabling. We could also point out that
d8
recognizes.mjs
, in case we want to add more examples than just Node.js.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I’ve updated my revision per your note.
The “no concept of MIME types or other mandatory hooks such as
type="module"
” language isn’t quite correct. As you know, Node has"type": "module"
now, which in fairness didn’t exist back when this sentence was written; but before you argue that the current text is still correct because of the “mandatory” qualifier that was added in response to Node’s"type": "module"
, keep in mind that HTML’stype="module"
isn’t mandatory either: a regular script can load a module viaimport()
, with notype="module"
in sight.But that’s just one clause, and the paragraph is stronger without it.
.mjs
’s utility is that it indicates a file’s module-ness for all non-browser environments and tools, rather than Node.js’"type": "module"
or Spidermonkey’s-m
or the various proprietary configuration options in Babel and Webpack and so on. I think that point comes across more clearly without the digression into.mjs
’s competitors.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, but the script doing the dynamic
import()
would be a classic script, not a module. The current phrasing is precise and correct, and I am not in favor of removing it.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Allow me to be blunt, if you don’t mind. The original sentence was this:
Then
"type": "module"
came to Node, and so that sentence was no longer true. So you added “mandatory” before “hooks.”As currently written, “mandatory” is a weasel word. It makes the sentence true again (arguably) but it is misleading to the reader in that it implies that
.mjs
is the only way to use ESM in Node. No reasonable reader would read this sentence and assume that there was any way to use ESM in Node other than via.mjs
. No one would read this and think, “oh, but does Node have any non-mandatory hooks?”If you want to recommend
.mjs
, that’s fine; my revised text makes that case for you, without deceptive language.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P.S. to my last comment: I didn’t mean to imply that you were being deceptive in your edit. I only meant that it comes across that way to me, and I’m hardly unbiased. Apologies if I came across otherwise.
We’re debating the wrong thing. The question isn’t whether the current text is wrong or incorrect; the question should be whether the new text is better. So let’s compare:
Both sentences offer a reason why
.mjs
is especially useful. The old sentence’s reason is why.mjs
is useful for platforms:.mjs
is useful for such platforms to have a way to be able to recognize modules. The new sentence’s reason is why.mjs
is useful for users: this is a convenient way to signal to platforms that a file is a module.As this article is written for users, I think the new sentence is more appropriate.