Node.js Now Supports TypeScript By Default

Refer

Source: Node.js Now Supports TypeScript By Default

Author: Matt Pocock

Translator: SenaoXi

Release Time: January 14, 2025

Translation and Republication Notice:

This translation is provided for educational and informational purposes only. All intellectual property rights, including copyright, remain with the original author and/or publisher. This translation maintains the integrity of the original content while making it accessible to chinese readers.

Modifications Disclosure:

This is a complete and faithful translation of the original content with no substantive modifications.
This translation includes minor adaptations to improve clarity for chinese readers while preserving all essential information and viewpoints.
Sections marked with [†] contain supplementary explanations added by the translator to provide cultural or technical context.

Rights Reservation:

If you are the copyright holder and believe this translation exceeds fair use guidelines, please contact us at email. We are committed to respecting intellectual property rights and will promptly address any legitimate concerns.

Key Points

Node 23 will soon be able to run TypeScript files directly without any additional configuration.

Marco Ippolito (who has been pushing for TypeScript support in Node for the past year) submitted a PR in Node 23 to remove the experimental flag from --experimental-strip-types.

This effectively means:

You can create index.ts files containing TS syntax (like type annotations).
You can run node index.ts directly without any additional parameters.
Node will use a version of swc to strip types and then run the generated code.

FAQ

How to Try This Feature?

The feature is now available in Node Nightly, as Marco mentioned. It will likely be released in Node 23 in a few days. Update: It looks like it will be released in version 23.6.0.

Will Node Type Check My Files?

No. Node won't type check files when running them. This is a good thing - it means type checking can happen in a separate process from your application running. You'll need to run tsc --watch locally to check your application's types while working.

What Should Be in `tsconfig.json`?

Here's a customized version of my TSConfig Cheat Sheet:

json

{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    /* Node Stuff */
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "module": "NodeNext",
    "noEmit": true,
    /* If your code doesn't run in the DOM: */
    "lib": ["es2022"]
  }
}

This might change in TS 5.8, as the TypeScript team plans to release a compatibility flag. It's not certain what it will be yet, but it will make interoperability with Node's TS support easier.

Are Enums and Namespaces Supported?

Enums and namespaces are not supported by default. Check here for other unsupported features. If you want to support other TS features, you can add --experimental-transform-types to make it work.

I'm not too sad about this, especially regarding the enums part.

Note that runtime namespaces are not supported, but type-only namespaces (using declare namespace) are. This is good - I like type-only namespaces.

Do I Need to Transpile to JavaScript in Production?

Node Applications

If you're deploying your code to serverless platforms, yes. Transpiling and minifying your code is crucial for good cold starts.

If you're deploying somewhere where cold starts matter less, then maybe not! There's a small cost when your application first loads TypeScript (it's really small), but once the process is running, it's unlikely to cause slowdowns.

One potential issue is if your code dynamically loads other TypeScript files during processing. This might cause some additional slowdown - so proceed with caution.

Libraries

Yes, you still need to transpile TypeScript to JavaScript before publishing libraries to NPM. There are two reasons:

To allow JavaScript users to still use your library.
TypeScript runs faster when using declaration files (.d.ts files), so not providing these means you're making your consumers' TS experience slower.

Monorepos

If you're creating a library in a monorepo that's only used within that monorepo, I still recommend transpiling TypeScript files to JavaScript.

The reason is the same as for libraries - the more .d.ts files in your monorepo, the faster the TS experience.

Will This Feature Come to Previous Node Versions?

Yes, TypeScript support will be added to Node 22, but not to Node 20. Marco mentioned this on X.

Contributors

XiSenao

Changelog

Last edited 21 days ago

View full history

Node.js Now Supports TypeScript By Default ​

Key Points ​

FAQ ​

How to Try This Feature? ​

Will Node Type Check My Files? ​

What Should Be in tsconfig.json? ​

Are Enums and Namespaces Supported? ​

Do I Need to Transpile to JavaScript in Production? ​

Node Applications ​

Libraries ​

Monorepos ​

Will This Feature Come to Previous Node Versions? ​