Add note about usage of ESM in source config file

[karlhorky]

trafficstars

Hi there, thanks for ts-node, it's super useful!

Quick PR to communicate that it's possible to use ESM as a module format in source files

Ref: https://github.com/facebook/jest/issues/11453#issuecomment-877655080

[cspotcode]

Can this be rolled into this page? https://typestrong.org/ts-node/docs/imports Can we improve the way the two pages are linked?

It's actually common knowledge in TS that you can use native import/export syntax regardless of the "module" option. We don't want to be in the business of explaining TS fundamentals, since that will always be handled better by TypeScript's own documentation.

With that in mind, can we link to TypeScript's documentation? Do they have a page explaining this?

[karlhorky]

It's actually common knowledge in TS that you can use native import/export syntax regardless of the "module" option

The general guidance is: TS should always be written with native ECMAScript module syntax

Interesting assertions, I haven't found anything to support this except some slightly similar language in this one other blog post: https://dev.to/darraghor/don-t-make-these-mistakes-using-ecmascript-es6-modules-in-your-next-node-js-application-4ki2

I have personally almost always written TS with standard ESM-style import and export up until now, except for some type definition files where I used the import x = require('x') syntax.

---

This is the closest TS documentation page to what I think you are looking for, but I don't see anything about recommending usage of ESM-style import and export: https://www.typescriptlang.org/docs/handbook/2/modules.html

---

As for moving it to the https://typestrong.org/ts-node/docs/imports/ page instead, I'm not sure that this information would have been useful for me on that page - I would have looked for it right beside the place with the overrides. To be clear, I have not been confused about ts-node itself - only about the wording and appearance of this moduleTypes configuration:

{
  "ts-node": {
    "moduleTypes": {
      "webpack.config.ts": "cjs",

My thoughts are: To see a moduleType of cjs right next to a path to a TS file seems like it could be confusing to read.

I suppose another option would be a different wording of the configuration option (moduleOutputs instead of moduleTypes):

{
  "ts-node": {
    "moduleOutputs": {
      "webpack.config.ts": "cjs",

But who knows - maybe you're right and this is a non-problem for everyone except me 🤷‍♂️

[cspotcode]

Interesting assertions, I haven't found anything to support this except some slightly similar language in this one other blog post:

The strength of my wording comes from answering beginner questions over the years. To make it simple for people, answers tend to migrate towards stronger and stronger recommendations over time. I can see how the word "always" might be triggering, because one can easily find exceptions to the rule.

I have personally almost always written TS with standard ESM-style import and export up until now, except for some type definition files where I used the import x = require('x') syntax.

It sounds like we're mostly on the same page. This is what I was thinking, that most TS users already write using import and export syntax.

Up into recently, TS on node was always compiled to CommonJS because that is the only thing that node supported.

I suppose another option would be a different wording of the configuration option (moduleOutputs instead of moduleTypes):

I opted for moduleTypes because we're not merely controlling the compiler's output, we're also telling node how to execute that output. This is a separate mechanism typically governed by node's package.json "type" field; hence moduleTypes. Node also refers to ES modules and CommonJS modules as the two module "formats." (link)

For some nitty-gritty details about why and how we are required to tell node which format to use, node docs here

To see a moduleType of cjs right next to a path to a TS file seems like it could be confusing to read.

I suppose this depends on if the reader knows that node uses a lot of CommonJS. To me, seeing node and "CommonJS" in the same sentence makes sense.

Webpack also has their own documentation; can we link to that? I believe it has complete examples of webpack.config.ts, showing the import and export syntax.

[cspotcode]

For what it's worth, I think the wording on https://typestrong.org/ts-node/docs/imports needs to be improved. The opening sentence is confusing. The following is too informal but might be an improvement:

The general guidance is: TS should almost always be written with ECMAScript module syntax, import and export statements. The question is whether or not we ask typescript to transform that syntax into CommonJS or not

This is copied from earlier posts but tweaked based on your feedback.

[cspotcode]

As a meta note, although I'm disagreeing and debating certain points, I appreciate the opportunity to discuss this, because documentation is hard and I don't have any editors helping me out. Thank you.

[karlhorky]

Webpack also has their own documentation; can we link to that? I believe it has complete examples of webpack.config.ts, showing the import and export syntax.

Yep, that is actually the content of this PR: https://webpack.js.org/configuration/configuration-languages/#typescript