Docs: What is TypeScript Node?

[adamhenson]

Desired Behavior

It would be great if the project would answer some fundamental questions in the documentation. In doing a variety of Google searches and parsing through issues, it's difficult to understand what exactly TypeScript Node does and how reliable it is. Below are some basic questions I think should be answered at the top of the documentation.

• What is TypeScript Node? This should be more than the current one sentence: TypeScript execution and REPL for node.js, with source map support.. I get it - it's an executor. But, if that's true - how or why is it transpiling (noticed the --transpile-only flag). If it is an executor, then why is there mention of compiling - noted in the How It Works section: TypeScript Node works by registering the TypeScript compiler for .ts, .tsx, .js, and .jsx extensions.. Does this mean compiling to C++ via just-in-time compilation to machine code the moment a piece of code is executed?
• How is performance... is it safe to use in production? I found a tease of this answer in Should I use it in production? #104 but it seems like an old issue and although some answers exist in that issue - there isn't a lot behind the answers for someone who doesn't know the details of what the code is doing from this project.

Is this request related to a problem?

No

Additional context

I'm doing some research about potentially using TypeScript Node with a large scale website and I need to make sure it is a reliable option that doesn't sacrifice performance. I'm having difficulty getting clear answers to those questions.

[cspotcode]

Does this mean compiling to C++ via just-in-time compilation to machine code the moment a piece of code is executed?

Before I answer, what is your experience level with TypeScript? Do you know how TypeScript is typically compiled and executed without ts-node?

[adamhenson]

Hi @cspotcode - I'm not an expert in TypeScript, however when I run tsc directly or let's say ts-loader... the code is transpiled to JavaScript. I run a build and get a set of built JS files and then I run Node against the built files... typically from an entrypoint like dist/index.js.

I'm trying to wrap my head around what TypeScript Node does as it seems to offer a runtime without a build step. Is it somehow transpiling (building) TS to JS under the hood during execution and somehow storing the result in memory (since it's not stored in the file system)?

The documentation seems to imply there is not a build step (which I've also noticed when running ts-node), that it is an executor. But the part I'm missing is how are the TS files compiled, when, and where is the result.

Please do correct my language if I'm saying something wrong.

[adamhenson]

I'm mainly wondering is there some kind of build happening at runtime? Is that happening up front, during execution and where is the resulting JS. Or does it somehow compile directly to machine code (C++)... not even sure if that's possible. I feel like I'm missing something that I'm not finding in the docs or any articles / Google searches. Starting to question my knowledge since I'm clearly in the minority :D

[cspotcode]

Correct, we execute the compiler in-memory, to do 2x tasks:

a) semantic analysis / typechecking. These are the errors that tsc normally emits.
b) emitted .js code. We store the .js in-memory. Vanilla node reads a .js file into a string, then executes that string. We hook into that process, so we read .ts into a string, the compiler compiles to .js, then we pass that .js to node to be executed.

We also install source-map-support so that stacktraces are converted to use .ts filenames, line and column numbers.

transpileOnly mode skips the typechecking, which is a feature of TypeScript's compiler APIs, exposed via require('typescript').transpileModule. You probably know that running tsc will emit .js files even when there are type errors. Using the APIs, we can transform .ts to .js without even attempting typechecking. Many users find this desirable, since there are many other ways to effectively typecheck code, and paying the performance hit for typechecking at startup is a bit silly if you've already done it elsewhere.

[adamhenson]

Great answer - thank you so much @cspotcode. This clearly spells it out for me. Maybe I could somehow put this answer in a PR that adds to the README (someday)

[cspotcode]

Happy to help. For what it's worth, I'm hoping to make a proper website for ts-node, to make documentation a bit friendlier and more discoverable. I'm working on that over here: #1207