What TypeScript configuration produces output closest to Node.js 18 capabilities?

by

As of Node.js 18.0.0, 100% of ES2022 is supported (apart from a bug in RegEx.flags), and support for ES Modules is stable! If you know that you are targeting that version or newer, the optimal config would look like this:

  • "module": "ES2022" & "moduleResolution": "node"

    Node.js 18 support loading modules instead of the old CommonJS format, we do have to tell TypeScript that we are using Node.js’s rules for resolving modules.

  • "allowSyntheticDefaultImports": true

    To provide backwards compatibility, Node.js allows you to import CommonJS packages with a default import. This flag tells TypeScript that it’s okay to use import on CommonJS modules.

  • "target": "ES2022"

    This tells TypeScript that it’s okay to output JavaScript syntax with features from ES2022. In practice, this means that it will e.g. output logical assignment operators & async/await syntax instead of embedding a polyfill.

  • "lib": ["ES2022"]

    This tells TypeScript that it’s okay to use functions and properties introduced in ES2022 or earlier. In practice, this means that you can use e.g. Promise.any and String.prototype.replaceAll.

The full config would thus be:

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "lib": ["ES2022"],
    "module": "ES2022",
    "moduleResolution": "node",
    "target": "ES2022"
  }
}

In addition to this, we also need to tell Node.js to treat .js files in this project as ES Modules. The reason for this is that Node.js had to maintain backwards compatibility with code written for older Node.js versions. This can be done by adding "type": "module" to your package.json:

{
  "type": "module"
}

Another change if you are coming from an earlier version of Node.js is that the file extensions when importing files are now mandatory. This means that you must write out .js at the end of your local imports. Note that this is .js even though you are importing a TypeScript file that actually has the file extension .ts. This might seem a bit confusing but this comment from one of the TS contributors explains why that is.

Here are some examples of how to write your import statements:

// Built-in Node.js modules
import { readFileSync } from 'fs'

// CommonJS packages from Npm
import md5File from 'md5-file'

// The local file "a.ts"
import { a } from './a.js'

If you want to stick with CommonJS for now, to avoid the caveats explained above, you can use the following config:

{
  "compilerOptions": {
    "lib": ["ES2022"],
    "module": "CommonJS",
    "target": "ES2022"
  }
}

If you are running Node.js 16 you can see my similar answer for Node.js 16 here

If you are running Node.js 14 you can see my similar answer for Node.js 14 here

If you are running Node.js 12 you can see my similar answer for Node.js 12 here

If you are running Node.js 10 you can see my similar answer for Node.js 10 here

If you are running Node.js 8 you can see my similar answer for Node.js 8 here

Leave a Comment

tech