upstream objection to --type

[MylesBorins]

specifically that the name of the flag --type is too generic. I've renamed it --entry-type. There is also the question regarding if it should be scope to entry point or be an alias to override package.type... basically the exact conversation from the last meeting

Latest comment nodejs/node#26745 (comment)
Implementation nodejs/node@59a4ef8

[GeoffreyBooth]

So we still have the issue raised in nodejs/ecmascript-modules#57 that basically, a flag that sets the module format of only the entry point introduces an issue where node --entry-type=module entry.js can import './file.cjs' which can then require('entry.js') and now we have entry.js loaded as both ESM and CommonJS. I don’t think an entry point-only override can work, and I also don’t see the use case for it (versus the flag setting or overriding the "type" field for the scope that the entry point is in).

I propose we rename the flag to --package-type and it sets or overrides the controlling package.json "type" field for the entry point’s package scope.

[MylesBorins]

I'd like to suggest the following behavior

• --package-type: if this flag is used it sets the type and overides the package.type field if it exists. If subsequent package.json's are found in children they are respected per the algorithm... e.g. it only overrides the base package.json
• if there is no --package-type the package.type field is used next
• if there is no package.type the default is commonjs

[ljharb]

At the moment, we only have consensus for a flag for the entry point - I agree that if it were a mode, and matched the type field, package-type would work.

[MylesBorins]

@ljharb I believe that we would have had consensus for this in the last meeting if you didn't object.

Are you +1 with moving forward for now? We can implement and have one more meeting for the team to review and +1 final implementation before landing

[ljharb]

with extending the scope of the flag to be a mode? no, I'm still not convinced a mode like that (especially settable via a NODE_OPTIONS environment variable) is a good idea for the larger ecosystem.

[devsnek]

i thought we voted and package scoped won

[ljharb]

As I recall, the one thing we voted on was whether .cjs was a blocker or not; and "keep .cjs" won.

[MylesBorins]

@ljharb can you expand on why please? I'd like to see this objection combined with a more in depth reason to object aside from "not a good idea".

I personally find the current behavior to be confusing and the ecosystem response to the current flag seems very much to be in line with the expected behavior that has been voice by multiple members of this team.

Up until this point we've been pretty good about respecting any objection, but now that we are moving upstream I think that objections need to come with a very strong and solid reasoning. In core, people cannot just "object" they need to have a strong case or that objection will be overruled, generally by the TSC.

Lone objections being unwilling to compromise will block our ability as a group to be chartered, the TSC will not want to charter a group that consistently requires their intervention.

edit: and I am unwilling to charter a group that consistently requires voting to handle objections

[WebReflection]

As previously mentioned, I believe --type=module|commonjs is the best way to go, and I don't see any compelling argument to define it ambiguous or inappropriate anyhow, specially because the type keyword was chosen to mimic the <script type="module"> Web behavior, making --type also future-friendly whenever new type could land on browsers.

However, if --type cannot be used, I'd like to discuss the alternatives I've read so far.

--package-type

This is super semantic and a no-brainer, but only if you think about the package.json field, otherwise it doesn't make much sense.

Example:

node --package-type=module standalone

I guess we agree there is no competition against node -m standalone, or even node --type=module standalone, specially when there is no package.json around.

--entry-type

Semantically speaking, entry and type combined make a lot of sense, but only in a CLI context.

If the package.json counter part is just type, instead of entry-type, having to remember the CLI switch VS the package one, is IMO unnecessary, inconsistent, overhead.

About -m

Even if this shortcut is limited to the module type only, it's pretty consistent with the rest of the CLI based ecosystem (SpiderMonkey / JSC) so, if there will be any shortcut, I think -m should be considered as special case over alternatives such as -t module or -et module

Expanding on entry-type opportunity

What I see as a missed opportunity with the current MR/state, is the ability to publish dual modules, as it's been done for the last couple of years.

The community already adopted the module field, and kept the main one reserved for CJS.

Various packages in npm are indeed published as such:

{
  "main": "cjs/index.js",
  "module": "esm/index.js",
  "unpkg": "min.js", // or "cdn" or others ...
  ...
}

If the current proposal is to use type as field to specify how the main one should be loaded, every package currently published as dual module won't be able to keep working as such (dual).

However, if we ask npm developers, AFAIK still part of this group too, if it'd be OK to have an entry-type field reserved in their package namespace, we could create a future-proof, present-ready, backward compatible, possibility to define any entry.

Example:

{
  "main": "cjs/index.js",
  "module": "esm/index.js",
  "entry-type": {
    "module": "esm/index.js",
    "commonjs": "cjs/index.js"
  }
}

Shortcutting as type (less ugly alternative)

If the previous idea would make people unhappy, or even better, if we keep the --type flag, how about asking npm folks if it's OK for npm to also trust/reserve a commonjs field?

{
  "main": "cjs/index.js",
  "module": "esm/index.js",
  "unpkg": "min.js", // or "cdn" or others ...
  "commonjs": "cjs/index.js"
}

The module field is somehow de-facto reserved in the package.json file, so how about we use --type to define which field of the package should be used?

As example, let's imagine a standalone file contains the following:

import module from 'package';

Now, there are three ways to run such file

# run standalone as commonjs
node --type=commonjs standalone

# run standalone as module
node --type=module standalone

# just run standalone
node standalone

The following algorithm, assuming the imported package has a related package.json, would apply:

[ edited few times, sorry ]

• if standalone is run as commonjs or without any type (default)
  • if there is no type field within the package.json
    • if there is a commonjs field within the package.json, require such file
    • otherwise require the main field
  • otherwise use the type information
• else if standalone is run as module
  • if there is no type field within the package.json
    • if there is a module field within the package.json, import such file as ESM
    • otherwise import the main field
  • otherwise use the type information
• else throw an "unsupported type" error

Above flow would always be able to disambiguate imports of any kind, keeping the ability to publish dual modules as it's been done until now, and as already managed by pretty much all bundlers.

Example of fully future/backward compatible package:

{
  "main": "cjs/index.js",
  "module": "esm/index.js",
  "unpkg": "min.js", // or "cdn" or others ...
  "commonjs": "cjs/index.js",
  "type": "module" // or "commonjs"
}

Above package would work in all current bundlers, providing entry points for both ESM and CommonJS, it would work in Node < 10 (or whatever version won't receive the --type flag), it won't require any maintenance for currently published dual modules, it'll always disambiguate through type when needed, it still offers fallbacks for CDNs or good old browserify.

Please note, I'm not saying people should produce dual bundles from now on, I'm saying these kind of packages has already landed in npm, and while things settle down with the new ESM module system, it might be handy to have a migration pattern that won't break the current ecosystem.

As Summary

I personally think keeping --type is the right thing to do, but I also would like to see such type reflected, and overruling, when appropriate, the main field, as that's been historically related to CommonJS, and specially in node.

Hope something I've written here could be considered, happy to answer questions, if any 👋

[GeoffreyBooth]

Reading through the comments on the upstream PR, it seems that everyone assumes that setting the type of the entry point therefore tells the project to operate in that mode. As in, they get that --type sets the mode of the entry point—but then they assume that therefore, .js files imported from an ESM entry point will be treated as ESM. @WebReflection above also makes this assumption.

So even if we rename the current feature --entry-type, a huge proportion of users will assume that that sets the type for their project, or rather for all files referenced in a tree starting from that entry point.

I can’t think of a use case for when a user might want to set the entry point type and not have that affect all the files in that scope. I can think of a use case where a package author might want an ESM entry point (to define named exports) for an otherwise CommonJS package, but a) packages aren’t run via flags, and b) there wouldn’t be a reason for a user to use a flag to override such a package/project. Absent a use case for the current behavior, I see no reason not to change it to the proposed package scope behavior and make the flag conform to user expectations (and use cases).