Run TypeScript Natively in Node.js

Yeah, so today we will talk about how we made it possible to run TypeScript directly in Node.js and why, and why not maybe CoffeeScript or Flow, or like, why TypeScript? So it doesn't matter. So let's start from the beginning. So if you were at the keynote today, we talked about the state of JS. And I have a very cool piece of history for you. This is the State of JS 2016 prehistoric. And we can see TypeScript was just at the beginning. We can see CoffeeScript and ClosureScript, a lot of technologies that were much popular than TypeScript, but then disappeared.

TypeScript has won the battle of the JavaScript superset. It is considered one of the most popular programming languages according to GitHub. It's on the rise. And JavaScript is going a little bit down. And also is one of the fastest growing languages in 2024. So if you come on the Node.js repo, open an issue, why don't you support CoffeeScript or Flow? This is the reason why. Because people did that. So it was fun.

As a Node.js project, we had a lot of issues. Please support TypeScript. Please, we want TypeScript. We want to be able to run Node.file.js, whatever. So there were years of discussions, years of like how we can do that. So there are a few challenges to this TypeScript support. The first one is that TypeScript does not have a spec. TypeScript is the implementation is the spec. And it does not follow SEMVer. So whenever it releases a new minor, it can have breaking changes. And that's a problem because Node.js has very strict stability guarantees. A Node.js release lasts about three years, while TypeScript moves much, much faster. So taking TypeScript as a library, putting inside Node, yeah, it's easy. But it's not what you want. You don't want breaking changes every three months.

Like you have your deploy breaking on a Friday. You don't want that. So that's why we could not take TypeScript as a library directly and put it into Node. Another issue was that until this year, when we released the required ESM in all the Node.js release lines, the interoperability was still an issue, was problematic. Now that issue has been solved so you can require ESM modules. And they are fully interoperable.

TypeScript requires source map or maybe that's what we thought, that TypeScript requires source map. This is not completely true because we found a way to run TypeScript without source map. But people were not happy about having source map because they are a huge performance penalty. They are prone to bugs. It's very hard to implement them correctly. And finally, no champion. Nobody wanted to do the work of implementing it, especially as a volunteer.

This was a lot of work. But one morning last year, I woke up and I opened this PR, which is the most upvoted PR in the Node repo. And it's add experimental strip types. So this was the first piece of running TypeScript natively in Node.js. So I did it just because I felt it. Like, no real reason. I just wanted to prove that it was possible to run TypeScript in Node. And this PR landed in 20 days, which was incredible at the time.

So what is strip types? What does it mean? And is it like really running TypeScript? What's going on? So this is a little piece of TypeScript code. Imagine we take a rubber and start erasing all the syntax that is not JavaScript. So interfaces are not JavaScript. So we can remove them. Types are not JavaScript. So we can remove them. OK, this is JavaScript, right? And we can run this piece of code. So essentially, this is type stripping. But we have changed the shape of our code. Is there a way that we can preserve locations? So as you can see, the length of the file has changed. The location in which the function is inside the file has changed. This requires source maps. And we don't want source maps. We don't like source maps. So is there a way to do this? So while I was working on the feature, someone suggested, why don't you replace the removed syntax with blank space? It was like, phew. Yeah, and we do that. So the output is going to look like this. And this works because you don't need source maps. So the location inside the file is matched one to one. So what is type stripping? Type stripping is removing the types from TypeScript. Everything that can be erased that is not JavaScript will be erased. It will not perform type checking. So type checking is something that only TypeScript can do as a library. There are no other implementations because there is no spec. So only TypeScript can do it. And you usually don't want to perform type checking at runtime. It's very expensive. It's going to slow down your development. You also have your IDE that will tell you when you are writing something that you should not write. And you usually perform the type checking in a pipeline or as a commit hook.

So it's not something that you run quickly. So we still think that you should install TypeScript to perform type checking. We don't want to put TypeScript in the runtime. It does not require tsconfig because we simply remove everything that is TypeScript specific. So there is nothing to configure. It only removes inline types. And we will see a bit later what it means inline types.

So not everything can be removed because there is some syntax that is not... affects the runtime. So it cannot be removed. It does not require source maps, which is the biggest win, in my opinion, of this approach. And it's stable across the TypeScript versions because TypeScript does not release new syntax in minor updates, only in major. So we can be consistent with TypeScript. And whenever there is a new syntax, we can update the transpiler in a Node.js major version.

So no breaking changes, no Friday spent debugging your pipelines. And that's very cool. Okay, so how did we do it? We created a library called Amaro. Amaro means bitter in Italian because the whole thing was a bit bitter. But yeah, you can install Amaro. It's a wrapper around SWC. So it's using SWC underneath. SWC, it's very popular. It's used by RSpark, Deno. It's battle-tested, so you can trust that SWC works well. And it's a custom version of SWC just for Node.

So with Node 22.6, we landed this flag, experimental strip types, that allows you to run TypeScript. In Node 23, we made it enabled by default. So you can just run node file.ts, and it works. It has some limitations because of the nature of type stripping. You can only... You have a limited TypeScript syntax that is supported. So only TypeScript features that require transformation are not supported.

An example are your beloved enums. I don't really like enums. I don't really like enums. But enums cannot be safely erased because they affect the runtime because they export value. So they cannot be erased. Namespaces that export values cannot be erased. So this syntax needs to be transformed into JavaScript. So enums, for example, are transpiled into this monstrosity right here. You can see. So if you like enums, this is what you get. We don't want code generation at runtime. So we decided not to support them.

Also, TypeScript, they agreed with us. And they created a new flag called erasable syntax only that will not allow you to use syntax like enums or other namespaces with runtime code parameter properties. So everything that cannot be erased, use this tsconfig flag and will be banned. So in Node 23.8 we added support for type only namespaces. Before we just banned namespaces. Now you can use namespaces, but only if they export type. So they are erasable.

So we know that a lot of people like enums. They want to use enums. So we created a new flag that is called experimental transform types that supports all the features that require transformation. This will be always flagged, will never be unflagged and probably will always remain in experimental state because you cannot rely on it completely, but you can use it while you transition to the type stripping.

Also, source maps are enabled by default because if you change, you generate JavaScript code then you need source maps and you have all the performance penalty and problems that we talked about before. So as I said, no TypeScript features that require transformation. No down leveling. What is down leveling? Supporting JavaScript features that are not yet in the JavaScript engine.

So an example is the using keyword in the explicit resource management proposal. So TypeScript would in the past polyfill this syntax in order to allow you to use it although it's not supported by the JavaScript engine. So we ignore this syntax. If it's supported by the JavaScript engine, you can run it. If it's not supported, you're going to have a runtime exception. This using keyword is now enabled in Node 24, so you can use it, but not in Node 22. You need to be explicit with the... When you import the file, you need to use the TypeScript extension rather than the JS extension.

So in the past, the TypeScript team was very feeling strongly about not using the .ts extensions even though the file was TypeScript because the result would be that it needed to rewrite the extensions at build time which is not 100% accurate. You could already, with this flag, allow importing this extension. Use the .ts extension, but if you try to compile, it would throw an error. TypeScript is unable to compile because it would need to rewrite this extension. But... So you would use the no emit or emit declaration only along with this flag to be able to type check. So it's type check only. But in TypeScript 5.7, a new flag allows users to rewrite the extension so you can use the .ts extension and at compile time, it will be changed into the .js extension because the file is transpiled. And it's called rewrite relative import extension, so you can write... You can use the .ts extension that is also compatible with Node otherwise Node will not allow using the .js extension if the file is TypeScript because at run time, that file is a TypeScript file. So you need to use this flag. You also need to use the type keyword if you are importing types because if... Let's take this example. So the top one is correct. Whenever you are importing a type, you need to use the type keyword because a node will erase all the erasable syntax and types are a piece of erasable syntax. So if you use the type keyword, Node will also erase the import itself because it's a type only and it's not affecting the runtime. But if you don't use the type keyword, Node will think that this is some code that you are running at runtime and it will not erase it but the export will be erased so you will have a runtime error. This is enforced by the verbatim module syntax from TypeScript and from the latest TypeScript version is enabled by default so you will have... Like TypeScript will get very mad at you if you don't use the type keyword. And finally, the most hated probably is running TypeScript Node modules. We had to artificially discourage users from running TypeScript Node modules. Whenever you try, you get this very long error and unsupported Node modules type stripping. The reason this was asked by the TypeScript team, they don't want the ecosystem to start publishing NPM package with TypeScript. Normally, there are a number of reasons why you should not do it. Maybe we can remove this limitation in the future but for now, we need to comply

Maybe we can remove this limitation in the future but for now, we need to comply. So, no TS in Node modules. This is the TS comb you should be using with Node for type stripping. If you want to take a picture, give you 10 seconds. These are all the flags that we talked about. So, erasable syntax only, verbatim module syntax, rewrite relative import extensions, and that's it basically. These three new flags.

I have three minutes so I will go very quick but this is a super cool, fun fact. I had to implement the evaluation of TypeScript code in Node. This is a piece of code. I hope it's big enough. It's an ESM code, as you can see, import from util and it's also TypeScript because const foo is a string. This is TypeScript ESM. How does Node detect that this is TypeScript ESM? First of all, it tries to compile it as a common JS module. It's not a common JS module so that's going to fail. Then it tries to compile it as an ESM module, but that's not an ESM module, it's ESM TypeScript. So, that's also going to fail. So, we try to strip the types. We remove the TypeScript types. So, we have a string that looks like this with a hole in the middle because we have removed the TypeScript types. So, if that fails, it means that probably you have syntax errors. So, we rethrow the original error with some enriched error message. Otherwise, we try again to run it as a common JS. It's not common JS again. We retry as an ESM module and finally we can run this piece of code.

As you can see, it's very expensive to detect syntax. That's why we created a new flag called dash dash input type. You can choose module TypeScript or common JS TypeScript. So, node will know what kind of syntax you are using, and so it skips all these passages, strips the types and execute it. But what about this? So, this is some TypeScript code, right? Is it? Okay, let's try to evaluate this piece of code.

But what about this? So, this is some TypeScript code, right? Is it? Okay, let's try to evaluate this piece of code. And the output is false. What the fuck? Why false? What's going on? And if you try in the browser, we also get false. Again, what's happening? Huh? Yeah, this is JavaScript syntax. This is not TypeScript. This is, well, it's also TypeScript, but it's also JavaScript. It's a function foo, so fetch is a global function. It's lesser than a global object. It's greater than a string and evaluates as false. So, this is crazy syntax ambiguity.

If we try to run this into the TypeScript playground, it will evaluate this as a fetch, not as false, which is inconsistent. This means that if you try to run this in nodes with the input type as TypeScript, it will evaluate as fetch. But if you don't specify it, it will evaluate as false. That's why TypeScript is not a real superset of JavaScript, by the way.

What are the next steps? Bug fixing and plugging in 22 and making it stable. We are working on this. So, some guy decided to bring TypeScript into the browser, so you can actually do TypeStripping in the browser with Amaro. You should not do it, but it's crazy that you can. A few days ago, I released Amaro version 0.1. We are bringing TypeScript stable in node 24. So, Amaro needs to be stable. We also removed the experimental warning from whenever you run TypeScript. So, from node 24, you will not have an experimental warning, so you should start using it.

It's still experimental, but probably before October, it will, maybe a bit later in October, will become stable. And finally, back part it to node 22. This will open the gates to TypeScript everywhere. And when node 20 will go end of life next year, every node version will be running TypeScript. So, please give it a try. For feedback, you can go to this repo. We have weekly meetings with the TypeScript team. And that's it. Thank you.

I wanted to start, though, with just asking, what was the inspiration for the just stripping types? It seems like it's a magical fix for not having to do with source code. It's like, where did that come from? So, while I was prototyping the experimental TypeScript support, one guy from Bloomberg was also working on TS blank space. So, Ashi Claymore. So, he suggested like, hey, I'm working on this. It's super cool. Like, why don't you do it? And I was like, this is brilliant. Let's do it. And we did it. Fantastic.

Is there now more collaboration between the Node.js and the TypeScript team in order to make sure that you're not blindsided by something in TypeScript 6 when that comes around? Yes. Every two weeks, we have a meeting with the TypeScript team. So, we started the conversation very early about this feature. And we got their approval to ship it. So, at the beginning, they were not super happy. But they embraced it. And now, they fully support it. They thought you were trying to just steal their thunder or something? Yeah. But the type checking is still important. It's the most important part, right? Yeah, absolutely.

Well, that's great to hear. Oh, we do have some questions coming through. Sweet. OK. Would you recommend using TypeStripping to run TypeScript code now? Or would you still compile first? It depends on your use case. If you're running, for example, something like HTTP server that lasts long. Because you have an increased startup time. Because you have to transpile. So, if you care about startup time, I would suggest to still compile. So, you have JavaScript. But if you don't care about startup time, you should definitely use it. It's stable. And go for it. Yeah, nice. OK.

A second question. Similar question. Do you encourage this on production projects? Or should we wait until the fall? I guess that... So, you mentioned October. Is that when that's node 24 going into LTS? Yes. Yeah, OK. Yeah. Yeah. Start using this now or wait till... You can start using it now. A lot of companies are using it. It's like... Has a wide adoption. So... That's awesome.

We're stable. Let's get going. Yeah, awesome. OK. Is this going to kill enums in TypeScript? That's one way of seeing it. But you could also think that maybe enums will come into the JavaScript spec. So... Is there a proposal for that? Yeah, there is a proposal. And it's the good enums proposal. Good enums. All right. So, if you want enums, if you... Well, I don't know. This question comes with a fingers crossed. Hopefully, it does kill enums. But if you want to see enums in JavaScript, in JavaScript, go check out that proposal. Go support that. Yeah. Awesome.

Is there a performance difference between TS Node or Node doing TypeScripting? Obviously, Node is much, much, much, much faster. I would discourage using TS Node because it does some monkey patching of Node internals. And it causes us a lot of trouble. Yeah. TS Node has caused me trouble recently as well. I don't know. It's like, stop using TS Node, I'd say. Use this. If you still got your enums in there, and you don't have non-strippable things, TSX is pretty good for that kind of thing. I mean, you can use dash dash transform types and it will run everything. Perfect.

Ooh, this is a good question. And one close to my heart as well. How is the developer experience of using TypeScript with the Node test runner? Smooth. It's fine. It's fine. Absolutely fine. Yeah. Yeah, cool. Super, super smooth. I did a little bit of work on this myself. And I've ignored it for a while.

Are we any closer to the coverage in Node test? I don't know if you know this. I think it's still experimental, but it's good enough to be used. Yeah, nice. Oh, yeah. More questions on performance and differences. I assume this is just the quickest way of doing. Any questions about performance? Type stripping in Node is the quickest way? Yeah, yeah, yeah. Nice. Another one on performance. So the question, I think you might have covered this, but let's do it again. The question is, I thought TypeScript had no real semantic versioning after 4.9 comes 5. Is it safe to depend on this? Yes, because the samver, so the breaking changes are more for type checking rather than syntax. Syntax is stable. I understand why they don't follow samver, because every time they break type checking, they had to release a major version, we would be at TypeScript 100 something. But syntax is stable. And that's why we discussed with the TypeScript team about this. Right. And it's only major versions that are going to change that syntax. And because you're talking with them more, that's all going to be fine, too.

Yeah. Awesome. Are there any collaborations planned between the Node team and like Bun or Dino for running TypeScript code? Do you talk with them about this kind of stuff at all? Not really. But if you work at Bun or Dino, we can talk. That's cool. Yeah. All right.

At what point? Is there a chance, is there a point where it's going to be possible to run any valid TypeScript app directly in Node? That is, without changing input statements, without removing your enums? I don't think so, because the subset of syntax that we decided to support is smaller. TypeScript gives you a lot of configuration, you can do all sorts of unholy kind of syntax, like import requires stuff that we cannot support, because that requires transformation, requires configuration, extensions, less imports, many things that we don't like. Our TypeScript implementation is JavaScript with types, and that's it. So whatever you're doing already in Node, plus types. Yeah, nice.

Yeah. I think it's actually fairly... With the flag in TypeScript, where you can say only use the strippable stuff, I think that is a good subset of TypeScript to pick up on and use. And it gives you those guardrails to make sure you're going to do things right for Node, and that you're not using enums, which most people don't seem to like. Exactly. All right, this is good. Okay. What's the biggest challenge that you had in implementing this? The biggest challenge was getting consensus. So it was not technically challenging, but getting consensus on landing this, it was wild, because people have different opinions. I got a lot of hate from social media like, oh no, this is not real TypeScript, and this is bullshit, but then people saw the value of type stripping, and then they became supporters, and they liked it. So was it the most upvoted and most downvoted issue? Not the most downvoted, but the most... Nice. Yeah. That's good. No, I mean, that seems... That points to a greater challenge in open source work on major projects anyway, is consensus and building that between people who want this stuff. Yeah. There's so much more to programming than there is just programming. Okay.

We're seeing more coming in, but we're running out of time right now. So I think this might be the last question, but how is this way of running TypeScript going to handle type definitions and runtime checking in something like Zod? Is there anything to worry about there, or we're all good? I think we're all good. Yeah? Yeah, I think it's working fine. I don't see why it would not work, but... Yeah, I mean, if you are running... Ahmed, I think, asked the question. If you're running projects using Zod, and you're having trouble with this, come and ask. There's a Q&A section after this downstairs. It's a good time to dig in deeper in the topic. And on that note, I will stop the questions there. But again, I want to thank you again, Marco. It's amazing that you implemented this. I think it's an absolutely brilliant feature for Node, and thank you for talking to us about it today. Thank you.