Accidentally adding type annotations to JS

I have ended up using typed JS on a few of my projects at work almost entirely by accident.

Like most other companies that make software in some form, we’ve been looking into improving our documentation.

Usually, in the node and JS world that leads you down the path of JSDoc and in an effort to find something with nicer output, I stumbled upon documentation.js which generates API docs from JSDoc annotations.

It also supports Flow annotations.

Which, on its own wouldn’t be enough to sway me because I’m one of those archaic people who believes that transpiling and building should be avoided at all costs. If unavoidable, then building should be deferred to deployment time.

Then I noticed that Flow supports a commented flavour of annotations that lets you avoid transpilation. And that works with documentation.js.

Which is how we almost accidentally started adding type annotations to our JS as a part of a documentation effort, after which the next logical step is to install flow and start using it.

Which was also easy to do in a very incremental way.

This process is pretty much the opposite of my experience with TypeScript which almost mandates an all-or-nothing approach and makes using non-TypeScript code and libraries almost uncomfortable to use. That’s in addition to forcing you into a transpilation/building process and a language variant that almost but not quite matches the current edition of JS.

Facebook clearly took a different approach to Flow than Microsoft did with TypeScript and it feels like Flow is just much more conducive to how most small-to-medium-sized projects work.

It seems to be working for us (so far). Your Mileage May Vary.

Baldur's Notes @baldur