tsimp

A TypeScript import loader for Node.js

Runtime
tapjs/tsimptapjs.github.io/tsimp/tsimp

README

tsimp 😈


A TypeScript IMPort loader for Node.js

What It Is


This is an importer that runs Node.js programs written in
TypeScript, using the official TypeScript implementation from
Microsoft.

It is designed to support full typechecking support, with
acceptable performance when used repeatedly (for example, in a
test suite which spawns many TS processes).

Why Is It


There are quite a few TypeScript loaders and compilers available!
Which one should you choose, and why did I need to create this
one?

- swc is a TypeScript compiler implementation
  in Rust
- tsx is a zero-config
  TypeScript executer that aims to be a drop-in replacement for
  node, powered by esbuild.
- ts-node is probably the
  most established of these, with a huge feature set and support
  for every version of node and TypeScript you could possibly
  want.

How this differs:

- It uses the TypeScript implementation from Microsoft as its
  compiler. No shade towards swc and esbuild, they're fast and
  can do a lot, but the goal of tsimp is strict consistency
  with the "official" tsc program, and just using it is the
  simplest way to do that.
- It supports the --import and Module.register() behavior
  added in node v20.6, only falling back to warning-laden
  experimental APIs when that's not available.
- Type checking is enabled by default, so no need to run an extra
  tsc --noEmit step after running tests, using a persistent
  sock daemon and a
  generous amount of caching to make it performant.
- It's just a module loader, not a bunch of other things. So
  there's no repl, no bundler, etc. Pretty much all it does is
  make TypeScript modules in Node work.

USAGE


Install tsimp with npm:

  1. ```
  2. npm install tsimp
  3. ```

Run TypeScript programs like this in node v20.6 and higher:

  1. ```
  2. node --import=tsimp/import my-typescript-program.ts
  3. ```

Or like this in Node versions prior to v20.6:

  1. ```
  2. node --loader=tsimp/loader my-typescript-program.ts
  3. ```

Or you can use tsimp as the executable to run your program (but
the import/loader is ~100ms faster because it doesn't incur an
extra spawn call):

  1. ```
  2. tsimp my-typescript-program.ts
  3. ```

Note that while tsimp run without any arguments will start the
Node repl, and in that context it will be able to import/require
typescript modules, it does _not_ include a repl that can run
TypeScript directly. This is just an import loader.

In Node v20.6 and higher, you can also load tsimp in your
program, and from that point forward, TypeScript modules will
Just Work.

Note that import declarations happen in parallel _before_ the
code is executed, so you'll need to split it up like this:

  1. ```js
  2. import 'tsimp'
  3. // has to be done as an async import() so that it occurs
  4. // after the tsimp import is finished. But any imports that the
  5. // typescript program does can be "normal" top level imports.
  6. const { SomeThing } = await import('./some-thing.ts')
  7. ```

By comparison, this won't work, because the imports happen in
parallel.

  1. ```
  2. import 'tsimp'
  3. import { SomeThing } from './some-thing.ts'
  4. ```

CommonJS require() is patched as well. To use tsimp in
CommonJS programs, you can run it as described above, or
require() it in your program.

  1. ```js
  2. //commonjs
  3. require('tsimp')
  4. // now typescript can be loaded
  5. require('./blah.ts')
  6. ```

In Node version 20.6 and higher, this will also attach the
required loaders for ESM import support. In earlier Node
versions, you _must_ use --loader=tsimp/loader for ESM support.