Alejandro Oviedo

Posted on Dec 11, 2023 • Edited on Nov 25

Node.js, TypeScript and ESM: it doesn't have to be painful

#typescript #node #esm

I was thinking into starting a Node.js project from scratch and had an unsettling choice to make: to use ESM or CommonJS.

The decision of a few popular package authors to adopt ESM, coupled with the ongoing maturity of the tooling, strongly suggests that it is the direction most of the ecosystem will converge to eventually.

In this article, my goal is to present a solution that is not only fast but it also leverages widely adopted and trusted tools.

🙅🏻‍♂️🛑 Disclaimer
This approach is thought to comply with applications running in Node.js, not on a browser. The module resolution will change drastically for other scenarios.

Make it ESM

The first step is to make the project an ES Module. To do that you only need to include "type": "module" in your package.json.
An annoying detail for me (transitioning from CommonJS) is that ES Modules require the file extension on your imports, like this:

import { hey } from './module-b.js'

We will see in the next section how it could be improved.

tsconfig.json

This is a minimal version of a tsconfig that worked for my use case.

{
  "compilerOptions": {
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ESNext",
    "isolatedModules": true,
    "esModuleInterop": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "outDir": "dist",
    "lib": [ "esnext" ],
    "types": [ "node" ],
    "baseUrl": "./",
  },
  "exclude": [ "node_modules" ],
  "include": [
    "src/**/*.ts",
    "bin/*.ts"
  ]
}

Notice allowImportingTsExtensions defined in there. This will allow to use your imports like the following:

import { hey } from './module-b.ts'

Compilation

I decided to use SWC to compile the project into JavaScript, primarily because of its speed. Bear in mind SWC will not run type-checking. For scenarios where type-checking is necessary, you can still use tsc to achieve this:

{
  "scripts": {
    "build": "swc src --out-dir dist/src",
    "build:ci": "tsc && npm run build"
  }
}

In order for the imports to work as expected this is the .swcrc config file that you will need:

{
  "exclude": "node_modules/",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "topLevelAwait": true
    },
    "target": "esnext",
    "baseUrl": ".",
    "experimental": {
      "plugins": [
        [
          "@swc/plugin-transform-imports",
          {
            "^(.*?)(\\.ts)$": {
              "skipDefaultConversion": true,
              "transform": "{{matches.[1]}}.js"
            }
          }
        ]
      ]
    }
  },
  "module": {
    "type": "nodenext"
  }
}

Live-reload

Also often times called hot-reloading, this functionality allows to watch your application files for changes and restart it when changes occur. I'm using SWC and nodemon to perform this, with exceedingly fast results. While using two different tools seems somewhat inconvenient I like it a lot because it leads to a single-responsibility goal: SWC only takes care of compiling our code and nodemon is in charge of watching JavaScript files and restarting the Node.js process.

Here are results showcasing the average time it took the server to restart, while watching for changes and running 10 times each using the example repository:

	time(avg)
tsx	260ms
SWC+nodemon	124ms

These numbers only measure from the time a change has been acknowledged to the new process has started successfully.

Why not include ts-node-dev in these benchmarks?
Sadly ts-node-dev is not currently compatible with the ts-node loader.

Running TypeScript files

There will be times when you need to run TypeScript files on its own. On Node v20 I couldn't make swc-node work for that (if you do, please let me know!), so I decided to use tsx. It works and is very simple to use.

{
  "scripts": {
    ...
    "migrate": "node --import tsx bin/run-migrations.ts"
    ...
  }
}

Final thoughts

Using TypeScript and compiling to ESM on Node.js involves a greater degree of complexity than is often recognized. There are a lot of tweaks and knobs to turn, and tools that are supposed to work but don't. I created an example repository with all the things I mention on this article in case you want to check it out: a0viedo/node-ts-esm-example

Top comments (14)

BinaryBitBytes • Dec 13 '23 • Edited

Thank you so much for this. I seriously had this problem today when dealing with imports from typescript to js and mjs.

Pablo Chiappetti • Mar 16

Thanks Ale :) Was struggling to understand current state of Node + TS + ESM support and you nailed it here.

Alejandro Oviedo • Mar 19

Glad it was helpful to you Pablito!

Liran Tal • Jan 24

Nice write-up Alejandro!

Do you find it a better alternative to avoid the "type":"module" and instead just use "main" and "module" as keys (potentially with "exports" too) to avoid the "type" declaration which hardly requires the project to run as a module too?

Alejandro Oviedo • Mar 19

Thanks @lirantal! I have tried alternatives but in the end type was simpler and easier for people to understand. I feel like "exports" is a rabbit hole where you need to know exactly what you're doing or you are lost.

Liran Tal • Mar 19

Yes agree that exports makes it a bit more harder on discovery :-)
Thanks!

fury-r • Mar 2

I tried the above .swcrc file. It didn't seem to work. I checked on playground got alot of errors.Finally i tried the below config it worked.Thanks for explaining how to do it.
{
"jsc": {
"parser": {
"syntax": "typescript",
},
"target": "es2022",
"loose": false,
"minify": {
"compress": false,
"mangle": false
}
},
"module": {
"type": "es6"
},
"minify": false,
"isModule": true
}
.swcrc

Jeff Tillwick • Oct 21

Can someone, for the love of all that is good, please explain to me in a way that actually makes sense WHY anyone would want to import something with an extension? PLEASE! Help me understand why ANYONE would want to do this?