Import specifiers in `--experimental-strip-types`

[GeoffreyBooth]

This is a dedicated thread for the issue of file extensions in import specifiers in TypeScript code. Refs: nodejs/node#53725 (comment), #208 (comment), nodejs/node#53725 (comment), nodejs/node#53725 (comment), among others.

Current proposal: Users write full filenames with extensions in their specifiers, similar to ES module JavaScript: import './file.ts'. Also, .ts extensions are required in require calls, similar to the .cjs extension in CommonJS JavaScript: require('./file.ts').

• This can be type-checked by tsc via the allowImportingTsExtensions tsconfig.json option.
• This aligns with ES module JavaScript and Deno.
• tsc cannot compile such TypeScript files into JavaScript (today) but many other build tools can. However, there’s not necessarily a need to compile TypeScript files into JavaScript when they can be run directly. The only benefit that a build step would provide would be for startup time performance (it would be slightly faster to evaluate JavaScript directly rather than stripping types from TypeScript and then evaluating it) and users concerned about this should arguably be using a full-featured bundler such as Vite rather than a one-to-one transpiler such as tsc.

Extension searching alternative: Users would leave off extensions, similar to CommonJS: import './file'. This is a very common way for TypeScript code to be written today, because most TypeScript code is transpiled down to CommonJS JavaScript where such specifiers are permitted.

• This can’t be supported in require statements, as it would be a semver-major breaking change.
• It would mean that we can’t add new file formats in the future without them also being breaking changes.
• If this is implemented by the same pass that replaces types with whitespace, where the extension is added before the source is evaluated, then we have the same problems introduced by supporting transforms: line and column numbers would shift and we would need to add support for source maps, slowing down execution.
• If this is implemented in Node’s resolution step, then resolution rules for ES module JavaScript would differ based on whether the importing module was a JavaScript file or a TypeScript file. This would be hard to document and explain, and would be a difficult edge case for userland customization hooks to need to support.

Replace .js alternative: Users would write import '/file.js' to refer to file.ts. This is what tsc recommends for users using tsc as their build tool, as it compiles .ts files to .js files one-to-one and never rewrites import specifiers.

• This is counterintuitive, as there are no .js files generated as part of running files via strip-types.
• What if both file.js and file.ts exist? None of the various options (error, load one file or the other) are obviously correct or consistent.
• Rewriting file.ts to file.ts is arguably something that’s logically handled by the build tool or bundler, as that’s the tool generating the file.js file to which the new import specifier would refer. It’s hard to see how it’s Node’s responsibility to make up for a shortcoming in a TypeScript build tool.
• If this is implemented in Node’s resolution step, then resolution rules for ES module JavaScript would differ based on whether the importing module was a JavaScript file or a TypeScript file. This would be hard to document and explain, and would be a difficult edge case for userland customization hooks to need to support.

[cspotcode]

In cases where some .js code is never compiled at all, and imports code that may or may not be compiled (it shouldn't have to know or care), the non-compiled code uses .js import specifiers to refer to .ts files. In production when these .ts files are compiled to .d.ts and .js, the code works. And in development using a loader, the .js resolves to .ts and the code works.

then resolution rules for ES module JavaScript would differ based on whether the importing module was a JavaScript file or a TypeScript file

Would not be true, because non-compiled .js can import .ts using a .js import specifier.

This is not as confusing as people think. Why should ./foo point to ./foo.js? There is no file foo on the filesystem. But ./foo logically maps to ./foo.js.

IIRC I implemented this behavior in ts-node: https://typestrong.org/ts-node/docs/options#experimentalresolver

[targos]

However, there’s not necessarily a need to compile TypeScript files into JavaScript when they can be run directly

What about package consumers who don't care about TypeScript? If packages are published without a build step, they will be left on the side or they'll have to run their application with the strip-types flag only because of their dependencies.

Also there's something that really needs a deep investigation: is the TypeScript type checker able to work with packages in node_modules that haven't gone through a build step that converts the .ts files to .d.ts? If the answer is no, we should definitely not recommend people to publish their packages without a build step.

users concerned about this should arguably be using a full-featured bundler such as Vite rather than a one-to-one transpiler such as tsc.

We are in deep disagreement here. I personally hate packages that are published as bundles.

[targos]

Also there's something that really needs a deep investigation: is the TypeScript type checker able to work with packages in node_modules that haven't gone through a build step that converts the .ts files to .d.ts? If the answer is no, we should definitely not recommend people to publish their packages without a build step.

I made some local tests and it looks like tsc and esbuild are able to consume packages with .ts files in the "exports" field, so that's good.

[kibertoad]

Other than .js => .ts extension that requires the flag allowImportingTsExtensions, and I'm strongly against supporting .js for ts imports,

@marco-ippolito Can you elaborate on this? Isn't supporting ".js" for TS imports consistent with how tsc works? Why introduce new semantics?

[marco-ippolito]

Other than .js => .ts extension that requires the flag allowImportingTsExtensions, and I'm strongly against supporting .js for ts imports,

@marco-ippolito Can you elaborate on this? Isn't supporting ".js" for TS imports consistent with how tsc works? Why introduce new semantics?

There is a typescript flag that allows .ts imports allowImportingTsExtensions, so it is supported. Its not the default but it is consistent

[targos]

There is a typescript flag that allows .ts imports allowImportingTsExtensions, so it is supported. Its not the default but it is consistent.

TypeScript does not allow to emit (transpile) code when this flag is enabled, so there's some level of inconsistency.
If I want to use --experimental-strip-types in development and publish my package on the npm registry, I will have to install two tools:

• typescript for type checking
• Something else that supports rewriting .ts specifiers to .js, for transpilation

[marco-ippolito]

There is a typescript flag that allows .ts imports allowImportingTsExtensions, so it is supported. Its not the default but it is consistent.

TypeScript does not allow to emit (transpile) code when this flag is enabled, so there's some level of inconsistency. If I want to use --experimental-strip-types in development and publish my package on the npm registry, I will have to install two tools:

• typescript for type checking
• Something else that supports rewriting .ts specifiers to .js, for transpilation

I believe this is something we can discuss with the TypeScript team as its a problem also shared by other runtimes

[GeoffreyBooth]

@cspotcode The point of type stripping is to not need to use a build tool or bundler. Deno and Bun run TypeScript files directly, including in production, and our type stripping is intended to do the same. Yes this means that startup time is slightly impacted, but that’s not very concerning for long-lived servers, which are the most common use case for Node apps. And if you’re coding for a use case where startup time does matter, like a CLI tool or a serverless/lambda function, then you shouldn’t simply transpile files one-to-one, you should bundle them like you would for the browser.

We are in deep disagreement here. I personally hate packages that are published as bundles.

@targos When I wrote that I was thinking of applications, not packages. But to your point, I think what we hate about packages published as bundles is when they bundle their dependencies, inlining them rather than treating them as external dependencies that can be deduped. I don’t think it’s terribly offensive when package authors use a build tool to optimize their library while externalizing dependencies, so that my app loads node_modules/foo/dist/lib.js and everything is in one minified file, but that file contains nothing more than foo’s code; any imports or requires to foo’s dependencies are still resolved to other packages under node_modules just like if a bundler hadn’t been used.

Maybe you’re also offended by package authors who minify or otherwise make their packages hard to debug at runtime, but ultimately you’re the one who’s choosing whose open source packages to use, and you can evaluate them based on whatever criteria you want. The Svelte team writes apps in TypeScript and libraries in JavaScript with JSDoc types, so that their libraries don’t need a build step yet can be consumed by anyone while still getting type checking, and that feels like the best model to me. If we're going to recommend anything, that’s what I would recommend.

What about package consumers who don’t care about TypeScript? If packages are published without a build step, they will be left on the side or they’ll have to run their application with the strip-types flag only because of their dependencies.

This is the same argument as any new or nonstandard syntax. We had this same discussion around --experimental-specifier-resolution=node: what if people publish packages that tell users they need to enable this flag in order to use their package? We could be having it today around --experimental-require-module: what if people publish packages that require(esm) and tell their users that they need to enable that flag in order to use their package? You could even make the argument today specifically about TypeScript: what if people publish packages in TypeScript and tell users they need to pass --import=tsx and run a particular tsconfig.json to run their package. And so on.

Generally public package authors don’t want their libraries to be hard to use, or they won’t attract many users. And private package authors, like corporate users writing packages for specific teams whom they know and can coordinate with, might choose to opt into experimental features since they know their users can handle it and want to. It’s not really our place to intrude in the relationship between package authors and consumers.

While I agree in principle that we should do what we can to prevent users from shooting themselves in the foot, where I draw the line is that I don’t think we should intentionally limit Node, blocking perfectly valid and unobjectionable use cases, just because some package authors might misuse a feature. By that logic we shouldn’t have shipped require(esm) because package authors might use it and publish packages expecting it to be enabled and some of their consumers don’t have it enabled. Limiting Node just isn’t the right solution for encouraging package authors to publish maximally compatible packages, and I don’t think it’s really necessary: public package authors generally want their packages to be used, so they have every incentive to publish with as broad a target audience as is feasible.

[GeoffreyBooth]

Also, the cat is already out of the bag: Bun evaluates TypeScript within node_modules:

mkdir temp && cd temp
mkdir -p ./node_modules/pkg
echo 'export const message: string = "Hello!"' > ./node_modules/pkg/index.ts
echo 'import { message } from "pkg"; console.log(message)' > test.ts
bun test.ts
Hello!

[mcollina]

tsc cannot compile such TypeScript files into JavaScript (today) but many other build tools can. However, there’s not necessarily a need to compile TypeScript files into JavaScript when they can be run directly. The only benefit that a build step would provide would be for startup time performance (it would be slightly faster to evaluate JavaScript directly rather than stripping types from TypeScript and then evaluating it) and users concerned about this should arguably be using a full-featured bundler such as Vite rather than a one-to-one transpiler such as tsc.

This is the biggest problem for me. TypeScript does not have a spec, but it has a reference implementation. If we evaluate code as .ts, a user would expect that code to be compilable by tsc.

[AlttiRi]

From #217 issue:

I strongly believe we should not support .js extension for .ts files.
The reason is that the compiler/bundler should be responsible to resolve the correct extension at compile time.

For distribution, if a developer cares about performance, he should provide already compiled .ts to .js.

Running .ts file is very useful (I already use this feature in Beta version of WebStorm), but mostly for development. One extra millisecond for file resolving is acceptable.

---

It would be fine, if @microsoft TypeScript team will change extend the behaviour of allowImportingTsExtensions.

Currently, it has the follow description:

Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set.

That requirement is unacceptable for library projects that use tsc --build for compiling with emitting .js/.d.ts/.map.js files.

I think, if the allowImportingTsExtensions will work without any "Requires", then importing of .js can be abandoned.

---

Here is a library config to compile .ts to .js with .d.ts files with tsc --build command.

    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noEmit": false,
    "declaration": true,

It works, but it requires to use .js in imports everywhere.

Adding "allowImportingTsExtensions": true, "breaks" it:

error TS5096: Option 'allowImportingTsExtensions' can only be used when either 'noEmit' or 'emitDeclarationOnly' is set.

---

I just say it again:

I think, if the allowImportingTsExtensions will work without any "Requires", then importing of .js can be abandoned in TS projects.

Why do these limitations exist?

This flag is only allowed when --noEmit or --emitDeclarationOnly is enabled, since these import paths would not be resolvable at runtime in JavaScript output files. The expectation here is that your resolver (e.g. your bundler, a runtime, or some other tool) is going to make these imports between .ts files work. *

Can't TS just replace ".ts" string with ".js" string in imports while compiling?

[Tobbe]

Can't TS just replace ".ts" string with ".js" string in imports while compiling?

No, because it might be a package named foo.ts 🙂

See also nodejs/node#53725 (comment)