Proposal: make .js extension default for es6 imports

[sheerun]

Just to be clear: this proposal is not to make --es-module-specifier-resolution=node a default

Backstory

Recently there have been a lengthy discussion I've started in order to make package.json of ES6 modules more simple. Probably the biggest takeaway from this is that without extensionless imports in some form, in order to create backward-compatible packages to support subpath imports like import first from 'lodash/first' they need to create long list of entrypoints in exports field of package.json which needs to be passed around everywhere.

This issue combines with obvious status quo that: many developers are used to, many existing applications already use, and many transcompilers (like typescript) application boilerplates (like create-react-app) generate extensionless imports in code: #323 (comment)

Probably the biggest "cons" against extensionless imports I've heard so far is that they are slow as they require checking few locations in filesystem in order to determine where the file is which is relevant if we want to use HTTP/2 streaming imports of non-transpiled JS files. But this seems an issue with --es-module-specifier-resolution=node which is only one solution to this problem.

Proposed solution(s)

Solution one:

If extensionless file is imported, assume .js extension.

• import App from "./App" always imports "./App.js"
• import App from "./App.js" always imports "./App.js"
• import App from "./App.mjs" always imports "./App.mjs"
• import App from "./App.cjs" always imports "./App.cjs"

This seems performant, accounts for status quo, and also seems to solve issue of complicated package.json for modules that support importing subpaths if exports is made stable.

For example this could be package.json of lodash package (please note that exports is not a part of this proposal, it is already a proposed and implemented thing)

{
  "main": "index.js",
  "exports": {
    "require": "./",
    "default": "./src/"
  }
}

• require('lodash/first') in old node loads CJS file lodash/first.js with old resolution rules
• require('lodash/first') in new node loads CJS file lodash/first.js because of require in exports (or old resolution rules if you decide to not change this behavior)
• import first from 'lodash/first' loads ES6 file lodash/src/first.js because of default in exports combined with the new resolution rule (default .js extension)

Solution two:

If extensionless file is imported, assume imported extension has the same extension as current file.

This means that:

• extensionless imports in .js files wil import .js by default
• extensionless imports in .mjs files wil import .mjs by default
• extensionless imports in .jsx files wil import .jsx by default
• extensionless imports in .cjs files wil import .cjs by default

etc. etd... Seems less opinionated but also more complicated

[ljharb]

In a browser, extensions mean nothing.

In node, .js means CJS, unless a package.json has "type": "module".

The only thing that unambiguously means ESM is .mjs, and as such, if we were to privilege just one extension, I'd say it has to be that one (unless it's a type module package, i suppose).

However, the other issue is, the importer has no say over the format of the module. Only the module author can possibly know how the module should be parsed, so any decision made about that needs to come from the module's code, its filename, or its closest package.json - never from "whether it's imported or required", for example.

[MylesBorins]

One of the other reasons to require explicit import sites is to make sure the tree is statically analyzable. Allowing a single dynamic entry point, such as only .js would violate that contract. This is important if we want to make authoring import-map, a feature for browsers that will allow supporting bare specifiers such as import 'lodash' out of the box.

import maps are already shipping in chrome behind a flag!

With export maps + explicit specifiers we can be guaranteed that we can generate an import map for an ESM tree and it will be import map compatible. If individual specifiers can be dynamic potentially a extensionaless file or a file with a .js extension code could not be shared without do static analysis of the code itself and dynamically updating the import map for cases where no file extension was used... that or transpilation.

[sheerun]

However, the other issue is, the importer has no say over the format of the module.

It has when it comes to defaults. You expect to import .ts from .ts files. .css from .css files, .scss from .scss files etc, .rb from .rb files and .java from .java files. The same way file imported from ES6 module is by default expected to be ES6 and one imported from CJS module is expected to be CJS.

This is not about what imported module is, but what it is expected to be and be found.

One of the other reasons to require explicit import sites is to make sure the tree is statically analyzable. Allowing a single dynamic entry point, such as only .js would violate that contract.

import-map supports "Packages with trailing slashes" which is compatible with this idea. Could you explain where exactly is the issue generating statically an import-map if .js is default extension?

[Jamesernator]

An alternative solution might be to allow some pattern matching in the exports map:

{
  "exports": {
    "regex:(\/.*)(\.js)?": "/$1.js"
  }
}

[hybrist]

One of the design constraints of exports was that it's possible to transform the data into a static resolution map (import map). So we would have to be reasonable certain that import maps are willing to add support for pattern matching which IIRC isn't the case.

[coreyfarrell]

Ref WICG/import-maps#7

[sheerun]

I don't think this would require regexps, something simple like this would suffice:

{
  "imports": {
    "lodash": "/node_modules/lodash-es/lodash.js",
    "lodash/": "/node_modules/lodash-es/"
  },
  "extension": "js"
}

Which automatically adds .js extension if non is provided and import is not found as exact match.

Although this example shows how it is possible to allow extension-less imports with import maps, it's not necessarily desirable. Doing so bloats the import map, and makes the package's interface less simple—both for humans and for tooling.

This looks like by-design flaw that could be solved by something as simple as above option.

[MylesBorins]

@sheerun keep in mind that import maps would only support adding file extension resolution for exported entry points. This would not support relative imports e.g. import './feature'

I'm not a big fan of attempting to shoe horn this into import maps for a couple reasons

• it is not a full solution of the problem, only partial
• it introduces a bunch of complexity for the manifest into what is otherwise a 1:1 mapping
• it introduces a bunch of complexity for the runtime for what is otherwise a O(1) operation (lookup)

While I appreciate your attempts to solve this I don't think this proposed solution is going to work

[sheerun]

It least I can try :) I appreciate the feedback because I don't see the whole picture. Even if group won't accept this into import-maps or node this discussion will be good reference

This would not support relative imports e.g. import './feature'

Indeed it seems that adding .js suffix (or js extension) needs to be defined for relative imports as well. It seems that import-map already controls behavior of relative imports by providing base path to resolve paths (https://github.com/WICG/import-maps#bare-specifiers-for-javascript-modules)

In the case of relative-URL-like addresses, they are resolved relative to the import map's base URL

I think defining additional behavior, like default extension that covers both relative imports and "trailing slashes" imports, is not that big deal.

it is not a full solution of the problem, only partial

This covers as much of the problem as possible given the "--es-module-specifier-resolution=node is not browser-compatible and computationally expensive" argument. If not, what are use cases that it doesn't cover?

it introduces a bunch of complexity for the manifest into what is otherwise a 1:1 mapping

For me it seems adding default extension is as much complex as "trailing slashes" imports which is already a part of import-maps

it introduces a bunch of complexity for the runtime for what is otherwise a O(1) operation (lookup)

This is still O(1)

[sheerun]

On extra note I don't argue for extension-less import because simply because I and others don't like adding .js extension to each import (which is already an argument on top of already mentioned ones). It is also because there exist at least 70000 of otherwise perfectly good ES6 packages in the wild that already use extension-less imports and .js extensions.

[hybrist]

It is also because there exist at least 70000 of otherwise perfectly good ES6 packages in the wild that already use extension-less imports and .js extensions.

I think there's a citation missing that those 70k modules are actually valid ESM. It would imply that none of them uses things like __dirname, none are relying on __esModule magic for imports of CJS dependencies, etc.. Afaik file extension isn't the only thing that stops most of today's babelscript/webpack modules from being runnable as actual native ES modules. From my experience .js is usually associated with non-ESM files, some of which may be using import syntax but most of them won't work in any actual ESM runtime. Because nobody ever tested those files in an actual ESM runtime.

[sheerun]

@jkrems Might be true, I won't argue about that

EDIT: the same way is hard to argue about uncounted number of applications that already use extension-less relative imports or extension-less trailing slash imports. Without ability to configure default extension they need to be converted and create mess in internal pull-requests

[hybrist]

If a project is serious about using native modules (beyond from bundler sugar), I assume that they’ll have to refactor to some degree. That’s one of the great things about .mjs: It allows to go through the code and migrate files incrementally. Add missing file extensions, remove bundler/compiler artifacts, and then mark the files that are meant to be actual ESM with .mjs. My base assumption is that any file with .js isn’t an actual valid ESM file.