A compiler option to enforce file extensions.

[trusktr]

Suggestion

A compiler option like requireExtensions would be great.

🔍 Search Terms

typescript compiler require import extensions

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

A compiler option like requireExtensions would enforce .js extensions to make modules ESM-compatible without additional tooling, imports maps, or package.json exports fields.

📃 Motivating Example

ESM ecosystem (Node, Webpack 5+, etc) follows the Node ESM standards. Tools like Webpack will throw a compile error on non-confoming ES Modules (when they don't conform to Node ESM spec), and Webpack full understands the package.json exports field when resolving modules for example.

💻 Use Cases

This would help to enforce writing code that is more likely to work well in strict Node ESM environments.

In Webpack 5, importing TypeScript output code that does no include extensions (although TS gives no error) results in a compile error for packages with "type": "module" in their package.json during Webpack's resolution (it behaves identical to Node ESM).

---

With requireExtensions set to false, the following code would be valid:

import {foo} from './foo'
import {bar} from 'some-lib'
import {baz} from 'some-lib/baz'
import {lorem} from '@org/some-lib/lorem'

With requireExtensions set to true, the following code would be valid only if moduleResolution is also set to "node":

import {foo} from './foo.js'
import {bar} from 'some-lib'
import {baz} from 'some-lib/baz.js'
import {lorem} from '@org/some-lib/lorem.js'

otherwise with a different value of moduleResolution it would probably need to be

import {foo} from './foo.js'
import {bar} from 'some-lib.js'
import {baz} from 'some-lib/baz.js'
import {lorem} from '@org/some-lib/lorem.js'

[pwhissell]

Because nodejs requires file extensions for relative imports,
This would be very helpful in modern nodejs projects trying to use ESM modules.
This will be more and more recurring upon TC39 module proposals being finalized (Top-level await, JSON modules, Module blocks, etc.)

[cherryblossom000]

In the meantime, you could use eslint-plugin-import's extensions rule with the "always" option to enforce extensions.

It would be nice if TypeScript could enforce this though. TypeScript should be able to detect simple runtime errors like not including a file extension in an import.

[rossng]

I think this is becoming increasingly important. There has been a significant move towards ESM-only packages in the last few months.

For example, I am using the d3-format package (2.6 million weekly downloads). The latest version has dropped CommonJS support entirely. After updating, I immediately ran into the fact that you can't import ES Modules from CommonJS. I flipped my tsconfig.json over to "module": "es2015", thinking that would solve it.

How naive I was! My project built fine, only to fall over immediately when launched in Node. The problem? My ESM import paths absolutely must have .js extensions to work.

After reading through the notorious #16577, I had the same thought as @trusktr. I'll tolerate spending a few hours to rewrite all my import paths with a .js extension. But it is absolutely critical for me that the compiler rejects invalid imports, and that tsserver/Intellisense suggests the correct ones.

Yes, you can set a config flag in VSCode, and add an ESLint rule. But not everyone uses VSCode, and some people will manage to avoid running ESLint. And that means that a catastrophic runtime exception will probably sneak into a production deployment at some point.

Adding this flag or a new moduleResolution option would fix it. Then there will be a simple and clear solution for the tens of thousands of developers who inevitably try to update a package in the next few months and smack head-first into this same problem.

[Hazmi35]

node-fetch just moved to pure ESM on v3.0.0-beta.10 too

[lizthegrey]

I am likewise here from https://blog.sindresorhus.com/get-ready-for-esm-aa53530b3f77#23d5 because p-limit package did the big breaking upgrade.

[trusktr]

Random tip: if you happen to be using Webpack 5 or higher, it will automatically complain if you forgot a .js extension. It's not a TS-specific solution, but at least it will help if you're already using Webpack.

This leads to a temporary workaround: you can test your code by running Webpack on it, even if you just ignore the result, and you'll get errors on missing extensions.

[andrewbranch]

This should probably be closed by #44501, in my opinion. It doesn’t make sense to say “make me write file extensions” outside the broader context of a module resolution strategy where file extensions are required, and --moduleResolution node12 is the first of those strategies that we’ll support. More exist; we still need a resolution mode well-suited for browser-flavored ESM, but new module resolution strategies are wholesale features that should be tracked as such.

[rossng]

Does #44501 enforce the presence of file extensions or does it magically transpile to the correct import statement? I couldn't figure it out from skimming the PR.

[andrewbranch]

It enforces file extensions. TS will never rewrite an import declaration’s module specifier under any mode, and in Node’s ESM implementation, file extensions are required, therefore we must make you write them.

[rossng]

Awesome. Sounds like this will work in browsers and support export maps too - I am really looking forward to it.