The Path to Native TypeScript

Welcome, everyone. I'm very happy to give this talk here at Node Congress. Today I will talk about the path to native TypeScript, so how Node.js and TypeScript have worked together to bring this new integration into Node.js.

Let me introduce myself. My name is Marco Ippolito. I'm a senior security engineer at Herodas and a member of the Node.js Technical Steering Committee.

So we will start with a little bit of history, so how and why we decided to support TypeScript and what changed in the past few years. So we will start with this chart. This is the state of JS 2016, so almost 10 years ago. And we can see that TypeScript was just at the beginning was not very popular. In fact, 34% of the respondents, they heard of TypeScript, but they were not interested into it. And just a small fraction was actually interested and has used it and would use it again. We can also see a few other names that have disappeared from the web development scene, like CoffeeScript, Elm and ClosureScript, but they were quite popular at the time. And we can see now more recent state of JS, which is the 2023. In this chart, we can see that almost all developers that responded, which are 17,000, they use TypeScript only 32%. And in like only 9% of respondents use JavaScript. So the majority of users use TypeScript in some like different percentages, but they all do. And this is crazy to think that 10 years ago, this was like very niche. And today, like everybody uses TypeScript. It's one of the most popular technologies. This is the Stack Overflow 2023 survey. And we can see that TypeScript is the fifth most popular programming language. So today we will see why Node.js has not integrated it years ago and this happened only now. So another very important data is the NPM downloads. TypeScript has around 12 million downloads per day. It is one of the most downloaded packages on NPM. So we will see today how TypeScript is supported in Node.js.

But let's talk a bit about the history. So as Node.js maintainer, I've always seen issues, discussions, PRs of users wanting native TypeScript support. As you can see, there are multiple issues and like there have been so many proposals on how to implement TypeScript in Node.js, but it never happened until recently.

And there are reasons why the implementation is not straightforward. One of the first challenges is that it's very hard to get consensus, Node.js being a project run by volunteers and open governance. It's very hard to make everyone agree on what it means to support TypeScript and how it should be done. There have been past attempts in 2023, there was a discussion at the Collaborator Summit in Bilbao, but the discussion, it eventually bled out. So it didn't happen.

There are different stability guarantees between Node.js and TypeScript. TypeScript does not follow SEMVer. So it means that every minor update has breaking changes while Node.js has strong security guarantees. So there is a new, like an LTS release of Node lasts for three years. So it's not possible to lock in a specific version of TypeScript for three years. And this big difference between the two, between Node and TypeScript makes it hard to integrate it. Node.js does not support a configuration file and therefore does not support TSConfig. Having Node supporting TSConfig, it would be weird. And it's something that would not get consensus because in the first place, Node does not have its own config file. So why would it support the config file of another project or dependency of Node.js, which is the reason why Node does not support TSConfig.

It's very hard to choose a tool that works out of the box. As we said, we cannot use TypeScript as an NPM package. We need to use something else. The reason why we cannot use TypeScript is because it's a very large NPM package. It's a 24 megabyte package. It's written in JavaScript and it would be very hard to integrate and not to mention the stability guarantees that we talked about before. So like there is not a single tool that fits the use case of Node and therefore it's very hard to choose. In the past, there were a lot of issues between CommonJS and ESM interoperability. So until those were fixed, it would have been a half-baked feature to integrate TypeScript. But now those are finally fixed. And so we had a chance to support TypeScript. Source maps. So whenever you transpile your code, you change the position of your code inside file by transforming TypeScript into JavaScript. So you would need source maps to be able to debug effectively and to reconstruct the location of everything in your source code. But source maps add a lot of overhead.

And if you enable them, you enable them globally, meaning they would also be enabled for your JavaScript. This is quite a problem because it would be a breaking change. And finally, no champion. It means that nobody wanted to do this work of having, like implementing the feature and having everyone to agree. Well, I did champion this initiative, so I started working on this in July 2024 and the way that I choose to implement TypeScript is called TypeStripping.

The way I implemented TypeScript is to not do type checking, only transpilation. The reason why is that type checking is the most unstable part of TypeScript and there is no spec. So the only way to perform type checking is through the TypeScript NPM package. So we expect users to download this package independently so they can upgrade their versions independently. They can configure their TSConfig without the runtime providing default values. And the problem is also that type checking is not something that you want. It's not something that you do during your development cycle. You only do like during CI or whenever you finish developing your feature. So you already have your IDE that shows you whenever there are errors in types. So this was not something that we wanted to provide as a runtime.

Also, since we don't want to support a TSConfig, this technique of TypeStripping does not involve TSConfig. TypeStripping, what it does is basically removes everything from TypeScript that is not JavaScript. And if the result is valid JavaScript, it will run it. It doesn't need a TSConfig because all the TypeScript features are removed. And this is exactly what it does. It removes inline types. Not everything is an inline type, so we will see that a bit later, how it works and what are the problems that arise from TypeStripping. But imagine that you define a variable that is a string. That little part string can be removed safely because it does not affect the runtime. It does not require source maps. We use a little magic trick to avoid changing the location inside the file during transpilation. So this solution does not require source maps, which means that the position in the file is one-to-one to where you write, it will be executed. And TypeStripping is stable across TypeScript versions because type checking is highly unstable, but the transpilation is quite stable. Doesn't change much. TypeScript has not added new keywords in a while, so it's pretty safe.

We talked with TypeScript team and they assured us of this stability. So how does TypeStripping work? We can imagine as this is some TypeScript code, we can just take a rubber and erase everything. So interfaces are not part of JavaScript. We can erase them. This is an inline type. We can erase it because it's not part of JavaScript. So the end result looks like this. This is valid JavaScript. So this is something that node can execute.

The problem is that this requires source maps because we have changed the position inside the file. But if we replace the syntax that we have removed with whitespace, is it possible to preserve the original location? So whenever we remove inline types, we replace them with blank space and therefore we don't need source maps. So to achieve this, we used a variant of SWC. SWC was in TypeScript. It's an NPM package that releases a WASM web assembly. So Node.js builds for many different platforms and having WASMs allows us to support all the different platforms that otherwise a Rust project would not support because Rust builds on different platforms than Node.js.

We needed something compatible with everything. It's battle tested because it's used by a lot of popular projects in the ecosystem, RSpark, Deno and so many projects use SWC. It supports type stripping. So it allows us to do what we talked about before. It's very fast and the maintainers are incredible. They helped us a lot. They were able to ship these customized versions of SWC in days since we started to work on TypeScript and this helped us a lot. So a big shout out to SWC maintainers. We decided to wrap SWC into a package called Amaro. So this allows users to upgrade their TypeScript and Spiler versions independently. So you can use Amaro as an external loader and this allows you not to be stuck on a TypeScript version. But if TypeScript releases new features, Amaro will be updated. You can use Amaro independently from the version used inside Node. So this is the reason why we wrapped into a package. So in July last year, I opened this PR to support experimental strip types.

This PR landed in 20 days, which is very fast considering Node.js time, which was great. So in Node 22.6, we shipped this new experimental flag called Experimental Strip Types. It has some limitations. So we can only support features that can be erased. Not all TypeScript features can be erased. Some of them, for example, namespaces and enums require to be transformed in JavaScript because they do affect the runtime. For example, this is a namespace and it exports a function, enums export some values. These are not just types. These are values and they cannot be erased. So if your namespace exports only types from Node 23.8, they can be supported. But if they export values that affect the runtimes, they cannot be supported. They will throw an error during translation. But to overcome this obstacle, we created a new flag called Experimental Transform Types. This allows you to consume all the TypeScript syntax. So this requires source maps to be enabled, but you can use enums, you can use namespace, you can use all the TypeScript syntax that you want at the cost of having source maps enabled.

For example, this is what namespace and enum looks like in JavaScript. So there is a code generation from TypeScript to JavaScript. And by default, we want to avoid this kind of code generations. Also, custom paths are not supported. Because it requires TS config, but you can use Node.js subpath imports that are supported and do exactly the same thing. So you can use them to alias a specific path inside your project.

So the first limitation, as I said, features that require transformation. We do not perform down leveling, which means that if it's a syntax that is going to be supported by the JavaScript engine, for example, decorators or explicit resource management, the TypeScript compiler will not perform transpilation of those because they will be supported eventually in a new Node.js version. So the using keyword, it will not be transpiled, it will not be down leveled into JavaScript that is compatible. So it will be left there. And if the JavaScript engine supports it, it will be possible to run it. Otherwise, it will throw a syntax error. Same for decorators. They will come soon into the language. So there was no reason to polyfill the behavior of decorators.

Another limitation is you have to be explicit when you import a file. If it's a TypeScript file, you need to use the .ts extension. Otherwise, you need to use the .js extension. In the past in TypeScript, we always have to use the .javascript extension when importing a file because that file would be transpiled into JavaScript. But at runtime, that file is a TypeScript file. So we need to be explicit. In the past, you were already able to use the .ts extension into TypeScript, but you could not transpile it. You could only use it in combination with the noemit flag. This behavior has changed since TypeScript 5.7. A new feature called path rewriting for relative paths was developed by the TypeScript team specifically to support Node.js experimental strip types. So with this new flag, during transpilation, it will rewrite the extensions to match the destination. So whenever you transpile a .ts file, it will become a .js file, and that will match. But what about existing source code? So it is possible with a code mode to migrate existing code base to support this behavior that Node.js enforces. You can use this code mode called correct-yes-specifiers by Jacob, one of the Node.js collaborators. It will transform all the syntax, all the imports that are not supported into imports that are supported.

This is a work in progress, so you can read more about this on NPM.

Another important limitation is that the type keyword is required for type imports. So whenever you are importing a type, you need to specify that that is a type. For example, in the first case, we import type 1 and 2. We use the type keyword. If we don't use it, Node.js will think that that is a value and not a type, so it will not erase it. While if it's a type, it can be safely erased, and it will cause a runtime error.

Also, an important limitation is that it's not possible to run TypeScript files in Node modules. This is to avoid disrupting the ecosystem because by publishing TypeScript, it would create a lot of incompatibilities. So if you ever try to run a TypeScript file inside the Node modules, we draw an error called unsupported Node modules TypeScript. The reason why this was specifically enforced by the TypeScript team is because it would cause a lot of compatibility versions, and your IDE would perform type checkings on Node modules, and we know how big Node modules are, so we don't want to do this. In Node 23.6, we enabled experimental strip types by default. So you can run Node file.ts by default without passing any flag.

Also, we have worked on TypeScript syntax detection in Eval. This is a very interesting topic. So this is, for example, we can see import util from util, and cost foo is a string value a word. This is a TypeScript ESM string. So Node.js tries to evaluate if the syntax is a common JS module, which it's not. It will try again as an ES module, but it's not because it's TypeScript. So that will fail. If it fails, it will try to strip the types, so it will try to transpile, like remove the string from this, the dot string type from this string. So foo now, this is plain JavaScript, and this is ESM plain JavaScript. So if this fails, it means that you have a syntax error, or the syntax is unsupported. So it will throw the error from the step two, plus the TypeScript compiler message. This is to avoid breaking changes in the error that is thrown. And it will try again to execute the string as a common JS, but we know it's ESM, so it will fail. And it will finally try again as a ESM module, which is correct. So you can see the syntax detection is very complicated. But you can skip all of this overhead by specifying which kind of syntax it is. So you can use the flag dash dash input type to say that this is a module TypeScript, or common JS TypeScript, and Node will know exactly what to do.

There is some syntax that is ambiguous. For example, fetch object. This looks like TypeScript, but this is valid JavaScript. If you try to execute it in Node, it will return false. And if you try in the browser, it would also return false. This is because the angular is detected as lesser. So it's a valid JavaScript syntax. And there is ambiguity because if you try to execute this in the TS playground, this will be executed as a fetch. So it will actually perform an HTTP call. If you try to execute it in Node with the input type as common JS TypeScript, it will also perform a fetch. So as you can see, the same syntax, if it's JavaScript or TypeScript, it changes the behavior. So this is a big problem.

TypeScript, in the latest release, announced a new flag called erasable syntax only. This will match the behavior of Node.js, so all the syntax that is not supported by Node.js will throw an error in TypeScript when you type check. This is very good because now you can type check and make sure that the syntax you're writing can be executed by Node. This is the TypeScript config that we suggest to our users. So all the flags that we talked about before.

And so what are the next steps? I will keep bug fixing it, I will work on making it faster and I'm working on flagging it in Node 22, and hopefully make it stable in Node 24 that's coming in very soon. So if you give it a try, you can join us on the Node.js TypeScript repo. We have meetings, you can check the Node.js calendar and that's it. Thank you for listening.