TypeScript tsconfig settings for Node.js 12?

Question

What is the optimal TypeScript tsconfig settings for outputting code that's going to be run on Node.js 12?

score 255 · Accepted Answer · edited Oct 02 '22 at 07:59

255

As of Node.js 12.0.0, 100% of ES2019 is supported. If you know that you are targeting that version or newer, the optimal config would look like this:

"module": "commonjs"

Node.js is on its way to add ES-Modules, but for now we'll have to stick with CommonJS.
"target": "es2019"

This tells TypeScript that it's okay to output JavaScript syntax with features from ES2019. In practice, this means that it will e.g. output object rest/spread properties & async/await syntax instead of embedding a polyfill.
"lib": ["es2019", "es2020.bigint", "es2020.string", "es2020.symbol.wellknown"]

This tells TypeScript that it's okay to use functions and properties introduced in ES2019 or earlier. In practice, this means that you can use e.g. String.prototype.trimStart and Array.prototype.flat.

In addition to ES2019, Node.js 12 also supports BigInt & matchAll from ES2020, therefor we include the additional definitions from ES2020.

The full config would thus be:

{
  "compilerOptions": {
    "lib": ["es2019", "es2020.bigint", "es2020.string", "es2020.symbol.wellknown"],
    "module": "commonjs",
    "target": "es2019"
  }
}

If you are targeting Node.js 12.9.0 or newer, you can simply specify "lib": ["es2020"] as that version supports all new functions and properties introduced in ES2020. It doesn't support the new JavaScript syntax though, so you still have to stay on "target": "es2019".

The full config would thus be:

{
  "compilerOptions": {
    "lib": ["es2020"],
    "module": "commonjs",
    "target": "es2019"
  }
}

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

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 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

edited Oct 02 '22 at 07:59

Liran H

9,143
7
39
52

answered Jan 17 '20 at 12:42

Linus Unnebäck

23,234
15
74
89

Does `"target"` affect `"lib"` in any way if `"lib"` is left empty in the config? If I just have `"target": "es2020"` what does `"lib"` default to? This has always been a source of mystery to me. – Sumomo Jan 28 '20 at 11:10
@Sumomo this answer (https://stackoverflow.com/a/50987516/148072) provides a little bit of insight. Although I haven't found any more info on what newer than "ES6" provides for default lib... – Linus Unnebäck Jan 28 '20 at 11:40
1

There is also [es2020.promise](https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2020.promise.d.ts) there now which is supported starting from Node 12.10.0. – Ivan Yarych Feb 26 '20 at 16:11
2

@IvanYarych the bottom part of my answer has a section for Node.js >= 12.9.0 which includes [es2020](https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2020.d.ts) which in turn includes es2020.promise – Linus Unnebäck Feb 26 '20 at 21:14
1

@LinusUnnebäck Thank you for these, they're refreshingly straight forward. I love that you went ahead and did one for Node 14 too. As far as a "citation" for this, does the TypeScript project publish these specific target and lib values for a given version of Node? – IAmKale May 20 '20 at 06:09
3

@IAmKale Than you for those kind words! The TypeScript does not publish that information, instead I've based the answers on mostly node.green, some testing myself, and the TypeScript documentation – Linus Unnebäck May 20 '20 at 08:34
I run tsc command. It throws "Argument for '--lib' option must be: ...." It's running on Node v.12.9.0. Doesn't ES current allow support? :( – Long Nguyen May 29 '20 at 02:15
@LongNguyen which version of TypeScript are you using? And what does it output where you wrote "...."? – Linus Unnebäck May 29 '20 at 12:10
1

When I use this config with Typescript `3.8.3` and node `12.13.0` and try to use bigint I get the following `tsc` error: `BigInt literals are not available when targeting lower than ES2020` – Piers MacDonald Jun 10 '20 at 06:56
2

@PiersMacDonald hmm, that is unfortunate. There doesn't seem to be a way to tell TypeScript that nullish coalescing isn't supported, while BigInt literals are. If you set target to ES2020 TypeScript will emit `??` which isn't supported by Node... If possible, I would recommend you to upgrade to Node.js 14 which supports the full ES2020 target. – Linus Unnebäck Jun 10 '20 at 09:02

score 25 · Answer 2 · edited Jan 27 '21 at 00:52

25

TL:DR

TypeScript maintains a mapping of target, module and lib corresponding to the node version. You can find it here https://github.com/microsoft/TypeScript/wiki/Node-Target-Mapping

edited Jan 27 '21 at 00:52

Pang

9,564
146
81
122

answered Sep 04 '20 at 11:56

rramakrishnaa

817
7
19

score 7 · Answer 3 · answered Sep 06 '21 at 09:34

It is much easier using tsconfig bases.

Run npm install --save-dev @tsconfig/node12 and then in tsconfig.json

{
  "extends": "@tsconfig/node12/tsconfig.json",
  // ...your configrations
}

There is a few tsconfig bases for different environments and the community keeps adding more.

TypeScript tsconfig settings for Node.js 12?

3 Answers3

Linked