RFC: Semantic Versioning for TypeScript Types ↩︎

In which years of thinking and months of design come to fruition.

Assumed Audience: Software developers, especially front-end devs, extra especially other TypeScript developers!

Epistemic Status: Mostly pretty confident we got this one right. Mostly.

Earlier today, I published Ember RFC #0730: Semantic Versioning for TypeScript Types. This RFC represents years of thinking about the problem space and having friendly conversations and arguments with collaborators and colleagues, and many weeks of writing effort over the last year. From the summary:

This RFC proposes a definition of Semantic Versioning for managing changes to TypeScript types, including when the TypeScript compiler makes breaking changes in its type-checking and type emit across a minor” release.(Note that this RFC addresses only type checking and type emit, not the transpilation” mode of the TypeScript compiler.)

While this RFC is being authored in the context of Ember.js’ adoption of TypeScript as a first-class supported language, its recommendations are intentionally general, in hopes that these recommendations can be widely adopted by the broader TypeScript community.

If you’re in the TypeScript community, or you care about SemVer, I’d love it if you gave the proposal a read and help us polish it up and fix any issues I missed along the way!


This is one of the biggest technical efforts of my career to date, and I think it has the potential to have a significant impact on the front-end community. I’m quite proud of it! TypeScript is an unusual language as mainstream languages go:

  • It provides a structural type system, whereas most other typed languages in general use have nominal type systems.

  • It is gradually typed, with explicit opt-outs for things which would be baked into the language inescapably in most other contexts and a wide range of compiler options to tune the strictness of the language.

  • It has a whole host of type system features that exceed anything else in a language in widespread use (pushing right up into the edges of dependent types!)

  • It releases new language and compiler versions roughly once a quarter, and every change may be breaking in small or big ways.

Writing a definition of SemVer for TypeScript, which can absorb all of that and help package authors provide stable types for their consumers… was a lot of work! A friend asked me yesterday, How long did it take you to write this?” Long-time collaborator James Davis (who, along with our other long-time collaborator Dan Freeman, is a huge part of why this is good if it is!), quipped:

That’s when you ask: do you mean putting words on the page or figuring out what even needs to be said?”

That’s exactly right: this is literally years of thinking, condensed into a few thousand words, written over the course of several intense weeks last May and June, with off-and-on revision ever since. I hope — very much! — that it ends up being useful to and therefore adopted by many TypeScript authors across the whole JavaScript ecosystem. Regardless, I’m just happy to have it out in the world… even if (or maybe especially because!) the development lead for TypeScript promptly found 8 issues to iterate on. (Truth be told, that’s better than I could have hoped, on many levels: only 8 problems?!? And: Ryan Cavanaugh took time to comment on it!!!) Here’s to the next phase for TypeScript with Ember — and hopefully for TypeScript users in general.