Roadmap for experimental TypeScript support

[marco-ippolito]

Intro

Since the previous discussion was successful in gathering feedback from the community, and I believe there is some consensus that this feature is something that the project wants to add, I want to summarize what are going to be the next steps and some technical solutions.
To be honest I'm very glad for the amount of feedback I received, it helped me to change my view on some aspects that I previously ignored.
Before I go into technical implementation, this is what the goals of this feature should be in my opinion:

Caution

These are long term goals and next steps, they might not reflect the current status.

• Make sure Node.js can support TypeScript with the stability guarantees that has always offered.
• Avoid breaking the ecosystem, this means creating a new "flavor" that only works on Node.js.
• Performance.
• Keeping it simple, we don't support everything, we want to user land tools to work in sync with Node, we provide the foundations to build on top.
• Type stripping is the way to go.

Step 1: Initial implementation

• module: add --experimental-strip-types node#53725

The initial implementation is the proof of concept that I have created to gather feedback and consensus from the project collaborators.
It's very far from being perfect but it establishes some of the points we want to move forward with.
Current limitations:

• No support forTypeScript features that require transformation (Enums, namespace, etc...).
• No .js extension for .ts files.
• No running TypeScript in node_modules.
• No source maps, but not needed because we perform whitespacing (replace removed code with white space).

Important

Why no support for TypeScript features such as enums, namespaces, decorators, etc...?????

• In the initial implementation I decided to start with the smallest subset possible.
• Adding transformation means supporting source-maps so is more work.
• Supporting features means adding more instability to the TypeScript syntax we support, without having a way to stay up to date with new features. As a general rule of thumb, the more you support the more likely to have breaking changes. This is a great challenge to overcome because we need to support transformations and new features but respect Node stability guarantees

Step 2: Decoupling

• Amaro as standalone loader feat: create amaro loader amaro#47

There is already a precedent for something that Node.js support, that can be upgraded seperately, its NPM.
Node bundles a version of npm that can upgraded separately, we could do the same with our TypeScript transpiler.

We could create a package that we bundle but that can also be downloaded from NPM, keep a stable version in core, but if TypeScript releases new features that we don't support or breaking changes, or users want to use the new shiny experimental feature, they can upgrade it separately.
This ensures that users are not locked, but also provides support for a TypeScript version for the whole 3 years of the lifetime of Node.js release.

Getting started

Create a new package called amaro that wraps swc with the current implementation. This package, which is released on npm, offers the same api that is currently used by Node, and it can be upgraded separately. The first challenge would be setup the project, make sure it can be upgraded by running npm install amaro@vX.Y.Z

Increase features

• Support for transformation behind a flag

• Enable support for TypeScript features that require transformation (Enums, mamespaces), now that we are decoupled we can expand on the amount of feature we support.

Caution

Currently there is consensus that Node.js should NOT run TypeScript files inside `node_modules.
It is not supported to avoid package maintainers to release TS only package.

Thanks @joyeecheung and @legendecas for the idea 💡

Step 3: Make it fast

• Benchmarks

With the project up and running, we can now start thinking about performance.
We could vendor SWC in Rust, build our own wasm, or compile it to static libraries that we could use in core, c++ rust FFI, etc...
I'm not a performance expert, but I think it is possible to optimize the interaction between Node and SWC and make it performant, without impacting the Node build process.
This is the phase where we measure the performance and make it usable in production without performance penalties.

Step 4: Add more features

• Amaro as Loader feat: create amaro loader amaro#47
• Rewrite .ts => to .js supported by TS 5.7 Rewrite relative import extensions with flag microsoft/TypeScript#59767

---

Wont Fix

• 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.
  At runtime, the extension must be correct, it doesn't make sense to add overhead in production when it can be solved during development. Discussion happening here: Import specifiers in --experimental-strip-types #214.
  This is also supported by TypeScript from 5.7 Rewrite relative import extensions with flag microsoft/TypeScript#59767
• Support tsconfig directly
  This would mean to run with typescript to support the latest flavors etc... Compilation and type checking should be done by user land tools during development.

[GeoffreyBooth]

I think this looks great; can we just replace the contents of the .md file in #210 with what you’ve written here? And then we can land that PR.

[silverwind]

No support forTypeScript features that require transformation (Enums, namespace, etc...).

Is there a definitive list of features that are not supported here? I'm looking to adapt my eslint config to match.

[marco-ippolito]

No support forTypeScript features that require transformation (Enums, namespace, etc...).

Is there a definitive list of features that are not supported here? I'm looking to adapt my eslint config to match.

it's documented here https://github.com/nodejs/node/blob/main/doc/api/typescript.md but you should expect it to change in the future

[jsejcksn]

There's a Getting Started article on the Node.js website — Node.js with TypeScript (source) — that might benefit from an update including information about this feature (once the time is right). I suppose a linked issue should be created in that repository, but wasn't sure whether it should be included somewhere in the list here, too.

[shawnmcknight]

• Enable running TypeScript files in node_modules

Caution

Currently there is no consensus whether Node.js should run TypeScript files inside `node_modules. Currently it is not supported to avoid package maintainers to release TS only package. I'm personally in favor of supporting it.

I understand the argument against encouraging package maintainers from releasing TS only packages. However, one additional thing to consider here is how node operates with internal packages in a monorepo. I'm not familiar with how other package managers work in this regard today, but pnpm will make links for internal workspace protocol packages as node_modules references in the dependent package. If node_modules support is not available, that would still then require a build step for any internal dependencies. I'm not sure how you could differentiate between these internal dependencies versus published packages, but being able to bypass a build step for internal packages would be extremely beneficial for monorepos structured this way.

[jakebailey]

I'm not sure how you could differentiate between these internal dependencies versus published packages, but being able to bypass a build step for internal packages would be extremely beneficial for monorepos structured this way.

I would think that this detail wouldn't matter because the realpath of these paths would leave node_modules. However, I'm not 100% certain how one would set up a monorepo with TS support via this flag anyway; you'd need to point things like export maps to TS files, making those export maps broken if packages are ever published, unless you go the "live types" route with a monorepo-local custom condition.

[shawnmcknight]

I would think that this detail wouldn't matter because the realpath of these paths would leave node_modules

This might just work out of the box then. I haven't tested with the new experimental flag yet, but it would be awesome if it just worked without any other considerations. 👍

However, I'm not 100% certain how one would set up a monorepo with TS support via this flag anyway; you'd need to point things like export maps to TS files, making those export maps broken if packages are ever published, unless you go the "live types" route with a monorepo-local custom condition.

In my use case, I wasn't thinking of publishing because the repo in question isn't published but is our internal backend runtime. With respect to things like export maps, converting them at build-time is actually how we make these internal packages work today. The exports and/or main properties in package.json are referencing the .ts files in the source. This allows for internal type checking to use the dependencies' .ts files and for ts-node to operate against the source file even in the dependencies. At build time, the exports and/or main properties are converted from src/*.ts to dist/*.js so the dependent packages are then using the transpiled JS.

I'm unsure if this is a common use case in the rest of the world, but I'm optimistic based on the realpath comment above that this might just work without any additional overhead.

[Daniel15]

Is the idea to eventually support other typing systems (for example, Flow, Hegel, or whatever comes next after TypeScript) like https://github.com/tc39/proposal-type-annotations proposes, or is this feature focused solely on TypeScript?

If it's only going to be for TypeScript, wouldn't it be better for the --experimental-strip-types flag to include typescript or ts in its name?

[alshdavid]

My understanding is that the inclusion of TypeScript support in Nodejs is to simplify the development cycle - where distributed code should still be transpiled to JavaScript before consumption (npm, production, etc).

Nodejs-valid TypeScript requires the .ts extension to be supplied in the import specifier. The issue is that there is no easy way to transpile imports with .ts extensions to .js.

The official TypeScript compiler does not support transforming imports due to the difficulty of handling dynamic imports.

SWC has a plugin that can rewrite import extensions, but it skips dynamic imports and is annoying to set up. Ideally, this additional tooling would be avoided as it diminishes the benefit of using built-in TS support over a loader.

Can we get guidance on how to properly transpile Nodejs-valid TypeScript to valid JavaScript for distribution?

[marco-ippolito]

Some discussion going on here #214.
I think we still need to figure out with @nodejs/typescript
1 - A recomended tsconfig
2 - How to solve the extension resolution during compilation
3 - add to amaro a way to perform the extension resolution wheh used as external loader

[silverwind]

Nodejs-valid TypeScript requires the .ts extension to be supplied in the import specifier. The issue is that there is no easy way to transpile imports with .ts extensions to .js.

The extension requirement comes from ESM support in Node which has always required a extension. I think it's a good requirement because it eliminates ambiguity when multiple files exist with the same name and it makes the module resolution faster. Imho people should find some codemod tool to adds the extension to their imports.

[JakobJingleheimer]

Imho people should find some codemod tool to adds the extension to their imports.

I'm working on creating one. I'll post once it's ready. I plan for it to correct bad file extensions (ex .js when the file is actually .ts and there is no such JS file) and when the file extension is altogether missing in the specifier.

[alshdavid]

The extension requirement comes from ESM support in Node which has always required a extension. I think it's a good requirement because it eliminates ambiguity when multiple files exist with the same name and it makes the module resolution faster. Imho people should find some codemod tool to adds the extension to their imports.

I 100% agree with this take. I think it was a good call to use explicit file paths as it avoids confusion and simplifies resolution.

[JakobJingleheimer]

Codemod is WIP: https://github.com/JakobJingleheimer/correct-ts-specifiers currently struggling with jscodeshift, which seems to be the biggest yet is almost completely undocumented (as is codemod itself 😢).

[Daniel15]

currently struggling with jscodeshift, which seems to be the biggest yet is almost completely undocumented

@JakobJingleheimer It's being worked on 😄 We (jscodeshift maintainers) launched a new docs site launched recently, but is still a work-in-progress: https://jscodeshift.com/build/api-reference/

Not sure if it's mentioned in the docs, but https://astexplorer.net/ is also a very good resource for inspecting the AST and writing codemods. https://codemod.com/ have Codemod Studio too, but I haven't tried it yet.

[alexbit-codemod]

Codemod is WIP: https://github.com/JakobJingleheimer/correct-ts-specifiers currently struggling with jscodeshift, which seems to be the biggest yet is almost completely undocumented (as is codemod itself 😢).

@JakobJingleheimer, founder of Codemod here (also maintaining jscodeshift, thanks @Daniel15 & @karlhorky for the mention)
would love to connect and help with any codemod questions, tooling, or documentation you need. feel free to ping me on X or in our community: https://go.codemod.com/community

[marco-ippolito]

@JakobJingleheimer we can add it to amaro and figure it out

[mitschabaude]

The codemod is a one-and-done step to fix issues in source-code, very similar to a migration; thereafter, just write the source-code properly and no extra tools are required.

@JakobJingleheimer there's a misunderstanding here. I agree it's no big deal to migrate an existing codebase from .js to .ts, I'd probably do that with find-and-replace.

However, that's not the issue that I was trying to bring up. The issue is in code bases that want to continue using tsc to compile their TS to JS, and therefore use .js. strip-types is incompatible with that flow.

(In case you wondered: no, I don't always want to use a third-party tool instead of tsc to transpile the TS source, to get .ts imports to work; tsc has more compatibility with tsconfig options and various TS versions than any other tool; also, what's the point of strip-types if I need a third-party transpiler in my toolchain anyway)

[mitschabaude]

Being first and wrong is still being wrong. That's not an argument in favour of changing our implementation (valid new arguments are welcome of course 🙂).

Ok! Then my argument is that changing your implementation would make strip-types more useful, and therefore more widely adopted.

[marco-ippolito]

@mitschabaude its clear there is incompatibility between tools.
From my point of view Node should not support guessing the extension.
I believe typescript is working to add a flag to emit import with '.ts' extension.
Also, this is an experimental feature, at an early stage, so its fair that is not fully compatible with existing tooling 🙂

[mitschabaude]

Also, this is an experimental feature, at an early stage, so its fair that is not fully compatible with existing tooling 🙂

Definitely and I didn't want to suggest that it should. I think the direction taken with strip-types is great, congrats on the work so far 🙌🏻

I'm really just talking about the roadmap for this feature. Currently the roadmap has the issue listed as "wontfix". I'd love for that to change. I'm also willing to help make strip-types work with js imports. My intuition is that this should be possible at no additional cost to currently supported use cases.

[JakobJingleheimer]

I don't always want to use a third-party tool instead of tsc to transpile the TS source, to get .ts imports to work; tsc has more compatibility with tsconfig options and various TS versions than any other tool

Is there a specific and compelling tsconfig option that only tsc supports? If so, that could be persuasive. I've used esbuild as my transpiler for quite some time though, and I've never encountered anything it couldn't handle.

Since everyone seems to agree TS's behaviour is wrong, I'm still inclined to say regardless that that would be TypeScript's problem, and you're asking us instead of them to change something because we actually consider feedback 🙃 (which is a little funny as I've so far basically been saying "no" 😅)

Buuuut as Marco pointed out, this may be moot if tsc is soon to handle proper file extensions.

I'm also willing to help make strip-types work with js imports.

Very appreciate that you're willing to contribute—contributions generally super welcome! However, there is significant opposition to this particular item within node, not to mention it would violate spec; barring a very unexpected persuasive argument (I'm not so arrogant to say I'm right no matter what 😉), I would block this. It is already possible and very easy to do this within node with tools that already exist: a resolve hook. I even wrote such a hook that will do what you want.

---

Should this be moved to a separate issue/discussion? I think this is getting a bit too specific for this general roadmap issue.

[allisonkarlitskaya]

I love absolutely everything that's going on here, so thank you to everyone who has been involved in it. I'm particularly impressed to see the communication and coordination going on between the node and TypeScript teams.

Here's a question from the peanut gallery: --experimental-strip-types has been released as part of v22.6.0. Will --experimental-transform-types land in some v22 release soon as well? It would be lovely to see this packaged in Fedora so that we can start playing around with it in earnest.

[silverwind]

I love absolutely everything that's going on here, so thank you to everyone who has been involved in it. I'm particularly impressed to see the communication and coordination going on between the node and TypeScript teams.

Here's a question from the peanut gallery: --experimental-strip-types has been released as part of v22.6.0. Will --experimental-transform-types land in some v22 release soon as well? It would be lovely to see this packaged in Fedora so that we can start playing around with it in earnest.

As I understand it, everything that's on main branch until the v22 LTS is forked on 2024-10-29 will be included in a upcoming v22 release.

[mitschabaude]

Should this be moved to a separate issue/discussion? I think this is getting a bit too specific for this general roadmap issue.

Agree, answered here: #214 (comment)

[marco-ippolito]

@allisonkarlitskaya yes, --experimental-transform-types is going to be released in v22.7.0 which is scheduled for today/tomorrow

[damianobarbati]

@marco-ippolito can't find proper info on the following, please let me know if I'm repeating a known issue:

1. How will it behave with dynamic imports? Will the flag be applied also to dynamically imported modules?
2. How will it deal with node_modules? Will it strips recursively?

I guess authors will have to compile/transpile the code because recursively stripping the imported files could result in breakage due to enums/namespace/decorators. Correct?

[marco-ippolito]

@marco-ippolito can't find proper info on the following, please let me know if I'm repeating a known issue:

1. How will it behave with dynamic imports? Will the flag be applied also to dynamically imported modules?
2. How will it deal with node_modules? Will it strips recursively?

I guess authors will have to compile/transpile the code because recursively stripping the imported files could result in breakage due to enums/namespace/decorators. Correct?

please refer to the documentation https://nodejs.org/docs/latest/api/typescript.html#type-stripping
To answer briefly:

• dynamic imports work as expected when they have .ts extension
• execution inside node_modules is not supported

If needed there is the flag --experimental-transform-types that supports enums, namespaces etc...

[franklin-ross]

Just gonna drop this here, for anyone looking to run node --experimental-strip-types and still have their .js imports work as expected.

https://www.npmjs.com/package/node-resolve-ts

[karlhorky]

Caution

Currently there is no consensus whether Node.js should run TypeScript files inside `node_modules.

Currently it is not supported to avoid package maintainers to release TS only package.

Will there be some discussion / meeting agenda items to come back around to TS type stripping support in node_modules?

The last agenda item I could find about this was these meeting notes from 2024-07-24:

• https://github.com/nodejs/TSC/blob/3f3606df0f44ac07a582128f068b3d699866a00d/meetings/2024-07-24.md?plain=1#L70-L83

As a user, it would be great to also have this ability that other runtimes like Bun have, especially for monorepos.

Personally, I'm looking to enable executable scripts in node_modules like this (to avoid a compile step for packages written in TypeScript which happen to be in node_modules):

bin/index.ts

#!/usr/bin/env -S node --experimental-strip-types

const a: number = 1;
console.log(a);

---

Edit: For anyone looking for an updated discussion, a dedicated issue nodejs/typescript#14

[mcollina]

There have been serious concerns raised by the TypeScript team about doing so.

I 100% agree with them, and I don't expect it to ship without a contested TSC vote.

[marco-ippolito]

@karlhorky There is consensus from both Node and from TypeScript that running ts in node_modules should NOT be supported. So I doubt that there will be discussion unless someone comes up with a very good reason. I will update the issue.

[adrian-gierakowski]

There have been serious concerns raised by the TypeScript team about doing so.

I 100% agree with them, and I don't expect it to ship without a contested TSC vote.

Could you please link to that?

[alshdavid]

Does the lack of node_module support break workspaces? Consuming sources within a workspace is a valid use case that would be a deal breaker for many projects

[mcollina]

The TypeScript team is concerned about the ecosystem consequences of users publishing TypeScript source files to the npm registry, and one way to discourage such an outcome has been to prevent type stripping support for files under node_modules. We would love to find a solution that allows type stripping to be used with monorepos and npm workspaces while avoiding encouraging users to publish TypeScript sources to the npm registry.

[karlhorky]

Edit: Copied to dedicated issue nodejs/typescript#14

---

I know that as a user I won't have much sway here, but I think I'm not alone in thinking that files in node_modules should also be allowed type stripping.

A few thoughts:

1) Node.js Alone Won't Prevent TS npm Publishing

There is a lot of movement in the "execute TypeScript, don't build it" ecosystem already, for example with the advent of many ecosystem projects such as:

• TypeScript execution CLIs like ts-node, tsm, tsx
• TypeScript-native runtimes like Bun and Deno
• modern TS-native registries like JSR
• somewhat related: ECMAScript proposal Type Annotations

Publishing .ts files to npm and other registries is already a growing pattern, which drastically reduces the effort and complexity of publishing a TypeScript package.

I think as these projects evolve and more people get to know about this possibility, there will be a greatly increased interest in this possibility.

It's my opinion that this banning of node_modules/*/*.ts in Node.js alone won't be able to hold back the energy in the ecosystem, especially with working alternatives. (not to mention users circumventing this by using any of the other projects, which do not have this limitation)

2) User Experience

My first experience with node --experimental-strip-types was creating an internal checking tool which was its own package, without a build step.

I immediately fell flat on my face with this, because of the banning of node_modules/*/*.ts files.

Even though I was already somewhat aware of the discussions and objections behind this, for my use case it felt like an arbitrary limitation imposed on my project.

I imagine that as type stripping becomes more widespread, this will be a common complaint from users.

3) Node.js Features Available Everywhere

@GeoffreyBooth wrote about supporting a Node.js feature everywhere:

If we support a file type, we support it everywhere. Just as module detection needs to apply within node_modules so that a package that works locally continues to work when published to npm, the same applies to TypeScript. We shouldn't be limiting our functionality to try to encourage best practices.

This resonates with me - it seems like supporting a Node.js feature in as many places as possible will be the best for users and cause the least amount of support complaints.

Banning node_modules/*/*.ts to try to avoid a pattern which the ecosystem may adopt seems like a weak reason. (not to mention that the ecosystem may end up adopting this pattern anyway by finding cowpaths around this)

4) Identifying and Addressing Downsides

Downsides as mentioned by Ryan and Daniel on the TypeScript team and vocal node_modules/*/*.ts opponents such as Matteo are important and should be considered.

But it feels like also:

1. Each problem should be carefully thought through, examined, clearly enumerated and documented (also asked for by Geoffrey)
2. Once clearly enumerated and documented, solutions should be also thought through, with each solution's tradeoffs being also enumerated and documented

This being done with a dispassionate, neutral stance, not trying to prove any one viewpoint.

In reading through the publicly-available documents, I don't think this has been done yet.

5) At Least Allow Users to Choose

Even if careful enumeration of problems and solutions leads to the final conclusion that the tradeoff is not worth it for Node.js, I think it would be good to allow users to choose for themselves and disable this node_modules/*/*.ts banning with a flag, eg:

node --experimental-strip-types-in-dependencies

[karlhorky]

Edit: Copied to dedicated issue nodejs/typescript#14

6) Similarities to .ts Rewriting Limitation

Oh one more thing, more related of a feeling than fact-based:

This node_modules/*/*.ts banning feels like it has a similar vibe to the .ts -> .js rewriting decision in TypeScript, which was overturned after years of doubling-down on .js imports (ironically heavily inspired by Node.js type stripping).

[robpalme]

Hello @karlhorky - thanks for the thoughtful input. @marco-ippolito mentioned in the most recent Node TS meeting that we haven't received much feedback on --experimental-strip-types yet, so your real-life experience is useful to hear.

Whilst this restriction is trivial to lift in terms of code changes in Node, the implications and opinions on doing so are significant. I'd suggest re-posting it as a dedicated issue on the https://github.com/nodejs/typescript repo to avoid thread-explosion here.

[karlhorky]

@robpalme thanks for the feedback! Copied to a dedicated issue here and edited my posts above:

• Type Stripping in node_modules/*/*.ts typescript#14

[alshdavid]

Sorry for bumping an old ticket, but in light of monorepo support currently only available through third party loaders (like tsx), it would be super helpful if Nodejs Workers would inherit --loader loaders from the parent process. This is a problem I am currently facing

[allisonkarlitskaya]

Hello @karlhorky - thanks for the thoughtful input. @marco-ippolito mentioned in the most recent Node TS meeting that we haven't received much feedback on --experimental-strip-types yet, so your real-life experience is useful to hear.

Is there somewhere where feedback is being solicited? I've played around with it a bit and found it to be a great replacement for tsx in the projects where we use it. The only downside, honestly, is the big scary warning and our concerns about depending on "too new" of a node version for our users.

[marco-ippolito]

@allisonkarlitskaya feedback is being received through issues/discussion is the nodejs/typescript repo