Today we’re excited to announce the release of TypeScript 5.8!<\/p>\n
If you’re not familiar with TypeScript, it’s a language that builds on top of JavaScript by adding syntax for types.\nWriting types in our code allows us to explain intent and have other tools check our code to catch mistakes like typos, issues with To get started using TypeScript, you can install it through npm with the following command:<\/p>\n Let’s take a look at what’s new in TypeScript 5.8!<\/p>\n Since our beta release<\/a>, we have had to pull back some work on how functions with conditional return types are checked.\nBased on some of the limitations and changes we wanted to make, we decided to iterate on the feature with the goal of shipping it in TypeScript 5.9.\nHowever, as part of this work, we added more granular checks for branches within return expressions.\nThis enhancement was not documented in the beta post, but will remain in TypeScript 5.8.<\/p>\n No new major changes have been added since the release candidate.<\/p>\n Consider some code like the following:<\/p>\n The intent of this code is to retrieve a URL object from a cache if it exists, or to create a new URL object if it doesn’t.\nHowever, there’s a bug: we forgot to actually construct a new URL object with the input.\nUnfortunately, TypeScript generally didn’t catch this sort of bug.<\/p>\n When TypeScript checks conditional expressions like In TypeScript 5.8, the type system special-cases conditional expressions directly inside This change was made within this pull request<\/a>, as part of a broader set of future improvements for TypeScript.<\/p>\n For years, Node.js supported ECMAScript modules (ESM) alongside CommonJS modules.\nUnfortunately, the interoperability between the two had some challenges.<\/p>\n In other words, consuming CommonJS files from ESM files was possible, but not the other way around.\nThis introduced many challenges for library authors who wanted to provide ESM support.\nThese library authors would either have to break compatibility with CommonJS users, “dual-publish” their libraries (providing separate entry-points for ESM and CommonJS), or just stay on CommonJS indefinitely.\nWhile dual-publishing might sound like a good middle-ground, it is a complex and error-prone process that also roughly doubles the amount of code within a package.<\/p>\n Node.js 22 relaxes some of these restrictions and permits TypeScript 5.8 supports this behavior under the Because this feature may be back-ported to older versions of Node.js, there is currently no stable For more information, see our support for require(“esm”) here<\/a>.<\/p>\n TypeScript 5.8 introduces a stable See more at both the Recently, Node.js 23.6 unflagged experimental support for running TypeScript files directly<\/a>;\nhowever, only certain constructs are supported under this mode.\nNode.js has unflagged a mode called That means constructs like the following are not supported:<\/p>\n Here are some examples of what does not work:<\/p>\n Similar tools like ts-blank-space<\/a> or Amaro<\/a> (the underlying library for type-stripping in Node.js) have the same limitations.\nThese tools will provide helpful error messages if they encounter code that doesn’t meet these requirements, but you still won’t find out your code doesn’t work until you actually try to run it.<\/p>\n That’s why TypeScript 5.8 introduces the Typically, you will want to combine this flag with the For more information, see the implementation here<\/a>.<\/p>\n In TypeScript 4.5, we introduced the possibility of substituting the default When installed, a package called This is a powerful feature, but it also incurs a bit of extra work.\nEven if you’re not using this feature, TypeScript always performs this lookup, and has to watch for changes in TypeScript 5.8 introduces the For more information, see the change here<\/a>.<\/p>\n In an effort to make computed properties have more predictable emit in declaration files, TypeScript 5.8 will consistently preserve entity names ( For example, consider the following code:<\/p>\n Previous versions of TypeScript would issue an error when generating a declaration file for this module, and a best-effort declaration file would generate an index signature.<\/p>\n In TypeScript 5.8, the example code is now allowed, and the emitted declaration file will match what you wrote:<\/p>\n Note that this does not create statically-named properties on the class.\nYou’ll still end up with what is effectively an index signature like Note that writing this code was and currently is an error under the Note that it’s possible (though unlikely) that a file compiled in TypeScript 5.8 may generate a declaration file that is not backward compatible in TypeScript 5.7 or earlier.<\/p>\n For more information, see the implementing PR<\/a>.<\/p>\n TypeScript 5.8 introduces a number of optimizations that can both improve the time to build up a program, and also to update a program based on a file change in either First, TypeScript now avoids array allocations that would be involved while normalizing paths<\/a>.\nTypically, path normalization would involve segmenting each portion of a path into an array of strings, normalizing the resulting path based on relative segments, and then joining them back together using a canonical separator.\nFor projects with many files, this can be a significant and repetitive amount of work.\nTypeScript now avoids allocating an array, and operates more directly on indexes of the original path.<\/p>\n Additionally, when edits are made that don’t change the fundamental structure of a project, TypeScript now avoids re-validating the options provided to it<\/a> (e.g. the contents of a This section highlights a set of noteworthy changes that should be acknowledged and understood as part of any upgrade.\nSometimes it will highlight deprecations, removals, and new restrictions.\nIt can also contain bug fixes that are functionally improvements, but which can also affect an existing build by introducing new errors.<\/p>\n Types generated for the DOM may have an impact on type-checking your codebase.\nFor more information, see linked issues related to DOM and Import assertions were a proposed addition to ECMAScript to ensure certain properties of an import (e.g. “this module is JSON, and is not intended to be executable JavaScript code”).\nThey were reinvented as a proposal called import attributes<\/a>.\nAs part of the transition, they swapped from using the Node.js 22 no longer accepts import assertions using the For more information, see the change here<\/a><\/p>\n The next version of TypeScript will be TypeScript 5.9, and we’ll have more details through an upcoming iteration plan on our issue tracker<\/a>.\nThat will have precise target dates and more details on upcoming features that we plan to work on.\nIn the meantime, you can try out early versions of TypeScript 5.9 today by installing our nightly builds<\/a> from npm with Until then, TypeScript 5.8 is here and ready to use, and we’re excited for you to install it today!\nWe hope that this release makes your day-to-day coding a joy.<\/p>\n Happy Hacking!<\/p>\n – Daniel Rosenwasser and the TypeScript Team<\/p>\n","protected":false},"excerpt":{"rendered":" Today we’re excited to announce the release of TypeScript 5.8! If you’re not familiar with TypeScript, it’s a language that builds on top of JavaScript by adding syntax for types. Writing types in our code allows us to explain intent and have other tools check our code to catch mistakes like typos, issues with null […]<\/p>\n","protected":false},"author":381,"featured_media":1797,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-4644","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-typescript"],"acf":[],"blog_post_summary":" Today we’re excited to announce the release of TypeScript 5.8! If you’re not familiar with TypeScript, it’s a language that builds on top of JavaScript by adding syntax for types. Writing types in our code allows us to explain intent and have other tools check our code to catch mistakes like typos, issues with null […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/4644","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/users\/381"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/comments?post=4644"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/posts\/4644\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media\/1797"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/media?parent=4644"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/categories?post=4644"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/typescript\/wp-json\/wp\/v2\/tags?post=4644"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}null<\/code> and undefined<\/code>, and more.\nTypes also power TypeScript’s editor tooling like the auto-completion, code navigation, and refactorings that you might see in editors like Visual Studio and VS Code.\nIn fact, TypeScript and its ecosystem powers the JavaScript experience in both of those editors as well!<\/p>\nnpm install -D typescript\r\n<\/code><\/pre>\nWhat’s New Since the Beta and RC?<\/h2>\n
Granular Checks for Branches in Return Expressions<\/h2>\n
declare const untypedCache: Map<any, any>;\r\n\r\nfunction getUrlObject(urlString: string): URL {\r\n return untypedCache.has(urlString) ?\r\n untypedCache.get(urlString) :\r\n urlString;\r\n}\r\n<\/code><\/pre>\ncond ? trueBranch : falseBranch<\/code>, its type is treated as a union of the types of the two branches.\nIn other words, it gets the type of trueBranch<\/code> and falseBranch<\/code>, and combines them into a union type.\nIn this case, the type of untypedCache.get(urlString)<\/code> is any<\/code>, and the type of urlString<\/code> is string<\/code>.\nThis is where things go wrong because any<\/code> is so infectious in how it interacts with other types.\nThe union any | string<\/code> is simplified to any<\/code>, so by the time TypeScript starts checking whether the expression in our return<\/code> statement is compatible with the expected return type of URL<\/code>, the type system has lost any information that would have caught the bug in this code.<\/p>\nreturn<\/code> statements.\nEach branch of the conditional is checked against the declared return type of the containing functions (if one exists), so the type system can catch the bug in the example above.<\/p>\ndeclare const untypedCache: Map<any, any>;\r\n\r\nfunction getUrlObject(urlString: string): URL {\r\n return untypedCache.has(urlString) ?\r\n untypedCache.get(urlString) :\r\n urlString;\r\n \/\/ ~~~~~~~~~\r\n \/\/ error! Type 'string' is not assignable to type 'URL'.\r\n}\r\n<\/code><\/pre>\nSupport for
require()<\/code> of ECMAScript Modules in --module nodenext<\/code><\/h2>\n\n
import<\/code> CommonJS files<\/li>\nrequire()<\/code> ESM files<\/li>\n<\/ul>\nrequire(\"esm\")<\/code> calls from CommonJS modules to ECMAScript modules.\nNode.js still does not permit require()<\/code> on ESM files that contain a top-level await<\/code>, but most other ESM files are now consumable from CommonJS files.\nThis presents a major opportunity for library authors to provide ESM support without having to dual-publish their libraries.<\/p>\n--module nodenext<\/code> flag.\nWhen --module nodenext<\/code> is enabled, TypeScript will avoid issuing errors on these require()<\/code> calls to ESM files.<\/p>\n--module nodeXXXX<\/code> option that enables this behavior;\nhowever, we predict future versions of TypeScript may be able to stabilize the feature under node20<\/code>.\nIn the meantime, we encourage users of Node.js 22 and newer to use --module nodenext<\/code>, while library authors and users of older Node.js versions should remain on --module node16<\/code> (or make the minor update to --module node18<\/code><\/a>).<\/p>\n--module node18<\/code><\/h2>\n--module node18<\/code> flag.\nFor users who are fixed on using Node.js 18, this flag provides a stable point of reference that does not incorporate certain behaviors that are in --module nodenext<\/code>.\nSpecifically:<\/p>\n\n
require()<\/code> of ECMAScript modules is disallowed under node18<\/code>, but allowed under nodenext<\/code><\/li>\nnode18<\/code>, but are disallowed under nodenext<\/code><\/li>\n<\/ul>\n--module node18<\/code> pull request<\/a> and changes made to --module nodenext<\/code><\/a>.<\/p>\nThe
--erasableSyntaxOnly<\/code> Option<\/h2>\n--experimental-strip-types<\/code> which requires that any TypeScript-specific syntax cannot have runtime semantics.\nPhrased differently, it must be possible to easily erase<\/em> or “strip out” any TypeScript-specific syntax from a file, leaving behind a valid JavaScript file.<\/p>\n\n
enum<\/code> declarations<\/li>\nnamespace<\/code>s and module<\/code>s with runtime code<\/li>\nimport =<\/code> aliases<\/li>\n<\/ul>\n\/\/ \u274c error: A namespace with runtime code.\r\nnamespace container {\r\n foo.method();\r\n\r\n export type Bar = string;\r\n}\r\n\r\n\/\/ \u274c error: An `import =` alias\r\nimport Bar = container.Bar;\r\n\r\nclass Point {\r\n \/\/ \u274c error: Parameter properties\r\n constructor(public x: number, public y: number) { }\r\n}\r\n\r\n\/\/ \u274c error: An enum declaration.\r\nenum Direction {\r\n Up,\r\n Down,\r\n Left,\r\n Right,\r\n}\r\n<\/code><\/pre>\n--erasableSyntaxOnly<\/code> flag.\nWhen this flag is enabled, TypeScript will error on most TypeScript-specific constructs that have runtime behavior.<\/p>\nclass C {\r\n constructor(public x: number) { }\r\n \/\/ ~~~~~~~~~~~~~~~~\r\n \/\/ error! This syntax is not allowed when 'erasableSyntaxOnly' is enabled.\r\n }\r\n}\r\n<\/code><\/pre>\n--verbatimModuleSyntax<\/code>, which ensures that a module contains the appropriate import syntax, and that import elision does not take place.<\/p>\nThe
--libReplacement<\/code> Flag<\/h2>\nlib<\/code> files with custom ones.\nThis was based on the possibility of resolving a library file from packages named @typescript\/lib-*<\/code>.\nFor example, you could lock your dom<\/code> libraries onto a specific version of the @types\/web<\/code> package<\/a> with the following package.json<\/code>:<\/p>\n{\r\n \"devDependencies\": {\r\n \"@typescript\/lib-dom\": \"npm:@types\/web@0.0.199\"\r\n }\r\n}\r\n<\/code><\/pre>\n@typescript\/lib-dom<\/code> should exist, and TypeScript will currently always look it up when dom<\/code> is implied by your settings.<\/p>\nnode_modules<\/code> in case a lib<\/code>-replacement package begins<\/em> to exist.<\/p>\n--libReplacement<\/code> flag, which allows you to disable this behavior.\nIf you’re not using --libReplacement<\/code>, you can now disable it with --libReplacement false<\/code>.\nIn the future --libReplacement false<\/code> may become the default, so if you currently rely on the behavior you should consider explicitly enabling it with --libReplacement true<\/code>.<\/p>\nPreserved Computed Property Names in Declaration Files<\/h2>\n
bareVariables<\/code> and dotted.names.that.look.like.this<\/code>) in computed property names in classes.<\/p>\nexport let propName = \"theAnswer\";\r\n\r\nexport class MyClass {\r\n [propName] = 42;\r\n\/\/ ~~~~~~~~~~\r\n\/\/ error!\r\n\/\/ A computed property name in a class property declaration must have a simple literal type or a 'unique symbol' type.\r\n}\r\n<\/code><\/pre>\nexport declare let propName: string;\r\nexport declare class MyClass {\r\n [x: string]: number;\r\n}\r\n<\/code><\/pre>\nexport declare let propName: string;\r\nexport declare class MyClass {\r\n [propName]: number;\r\n}\r\n<\/code><\/pre>\n[x: string]: number<\/code>, so for that use case, you’d need to use unique symbol<\/code>s or literal types.<\/p>\n--isolatedDeclarations<\/code> flag;\nbut we expect that thanks to this change, computed property names will generally be permitted in declaration emit.<\/p>\nOptimizations on Program Loads and Updates<\/h2>\n
--watch<\/code> mode or editor scenarios.<\/p>\ntsconfig.json<\/code>).\nThis means, for example, that a simple edit might not require checking that the output paths of a project don’t conflict with the input paths.\nInstead, the results of the last check can be used.\nThis should make edits in large projects feel more responsive.<\/p>\nNotable Behavioral Changes<\/h2>\n
lib.d.ts<\/code><\/h3>\nlib.d.ts<\/code> updates for this version of TypeScript<\/a>.<\/p>\nRestrictions on Import Assertions Under
--module nodenext<\/code><\/h3>\nassert<\/code> keyword to using the with<\/code> keyword.<\/p>\n\/\/ An import assertion \u274c - not future-compatible with most runtimes.\r\nimport data from \".\/data.json\" assert { type: \"json\" };\r\n\r\n\/\/ An import attribute \u2705 - the preferred way to import a JSON file.\r\nimport data from \".\/data.json\" with { type: \"json\" };\r\n<\/code><\/pre>\nassert<\/code> syntax.\nIn turn when --module nodenext<\/code> is enabled in TypeScript 5.8, TypeScript will issue an error if it encounters an import assertion.<\/p>\nimport data from \".\/data.json\" assert { type: \"json\" };\r\n\/\/ ~~~~~~\r\n\/\/ error! Import assertions have been replaced by import attributes. Use 'with' instead of 'assert'\r\n<\/code><\/pre>\nWhat’s Next?<\/h2>\n
npm install typescript@next<\/code>, or by using the VS Code TypeScript Nightly<\/a> extension.<\/p>\n