"We will soon migrate to TypeScript, and then..." – how often do you hear this phrase? Perhaps, if you mainly work within a single project or mostl...
For further actions, you may consider blocking this person and/or reporting abuse
Thx for that image which was clerify to me the jsDoc unite type declaration format which help me to write this one a much more easy format:
Currently I was working on a jsdoc react state handling npm module:
jsdoc-duck
-- convert to ->
You can export a type without making a variable:
This automatically exports the type.
With TS pre 5.5, you can import it like this in another file:
With TS 5.5 and above, you can import with JSDoc
@import
syntax:Basically just wrap an import statement with
/**@
and*/
to convert it to type-only import comment.If you want to avoid
@private
, you can use official JS private syntax:Also check out some proposals for simplified and more concise type comment syntax here:
github.com/microsoft/TypeScript/is...
For example see how concise this is compared to JSDoc:
Hey @trusktr ! Thank you for your answer and advice!
I knew about auto-import when the type is declared via JSDoc comments and also about the new
@import
feature (I followed and contributed to the discussion on this feature here). However, I prefer the type declaration usinglet
+ JSDoc comments, as shown in the screenshots above. The main issue with using comments is that there are no ESLint rules to lint them. It's easy to forget to delete something because rules like "no-unused-vars" or "sorted-imports" don't work for type declarations and imports in JSDoc comments.The issue about annotations as comments is really good! I wasn't aware of it. I've subscribed to it and will follow all the discussions. Thank you!
I've never been a fan of fully typed versions of untyped languages, specially of the interpreted variety (as this effectively makes them compiled languages, without really giving them any of the associated performance benefits).
First for Lua, then recently for JavaScript I've also landed on type annotations in comment form that a language server can use to check my code as I am writing it, but that doesn't need any additional build steps.
I've now gotten so used to this way of structuring my code that I am starting to miss it when writing Ruby code, but alas, I haven't yet found a LS that will do this sort of "optional" type checking properly (solargraph tries to but is kind of weird about it).
Hey @darkwiiplayer !
I understand and support your points. I would like to see more JavaScript tools that can check code for type safety. This could create stronger competition, thereby pushing the development of tools faster. But for now, we have to live with what we have 🥲
I hope that the ES types proposal, if it will be accepted, could enable the creation of more tools that will help with this
The issue with JSDoc is that you end up writing TypeScript in your docblocks anyway. Your code examples are full of TypeScript annotations, so it's not that you're moving away from TypeScript, it's just that you're putting it somewhere else.
In your example screenshot of commit changes, the fundamental difference between the new version and the old version is that you've made a single use type declaration into a reusable one. The aesthetics don't matter, it's the fact that you've made a reusable type declaration that's important.
Putting all your types in docblocks leads you to a situation like this:
It's fine if
obj
is of a type that's only used in this one place. But in reality it the type ofobj
will be used multiple times, so it's simpler to declare the type once:Even if your codebase is JS using docblocks, this is a much neater solution:
Even better if you move your types into the function declaration, then you can use the docblocks for the actual documentation:
This was a simple example... If you have functions with multiple shapes, union types, optional arguments, default values, or destructured arguments, then the docblock version becomes even more unwieldy.
I'm not so sure if this is accurate.
In my experience, the difference in build time between the two is negligible. The additional time you refer to is the time it takes to perform type checking. If you don't check types when you build, then a project that uses Vite / Webpack / Babel etc will take roughly the same time to build.
If TypeScript build times were really much larger as you say, we wouldn't see people using TypeScript in large projects. But we do, because when you save a TS / JS file and HMR kicks in, the build time is negligible in both cases.
Again, it's not the build it's the type checking that takes time, and you should consider type check as a separate step to build.
See
ts-loader
documentation here for example:If you follow this advice and disable type checking at the build stage, regardless of your tooling, you'll get faster builds. Personally, I only do type checking once I am ready to integrate my changes into an upstream branch.
This just means that you're using TypeScript. :)
Hey @teamradhq !
Thank you for your comment, and especially for your code snippets! Let's go step by step 🙂
I completely agree that it's better to extract such types into separate files. This applies to both JSDoc and TypeScript, as well as the programming language in general. Making the code more readable and decomposing it is independent of any particular language, and, of course, it's always better to do so whenever possible (though unfortunately not always feasible).
Also, I would like to add that I can declare these types using JSDoc syntax in
.js
files without the need for.ts
files. Here's an example of how it can look:I use TypeScript syntax in JSDoc simply because I chose it. However, it doesn't prevent me from using, for example, the Closure Compiler syntax as well.
Trust me 🙂
Here are two screenshots from one of my presentations where the build took a whopping 17 minutes. It's quite an old presentation that uses create-react-app (yes, with various ENV options like
CI=false
and others). Without.ts
files, the build took around 2 minutes.Btw, the presentation itself is about migrating to Vite. Eventually, after all the optimizations, the build started taking around 1 minute (even with
.ts
files). But that's because I have experience and know what to do. For most people, doing such optimizations for the first time will be a significant journey.This means that I am currently using TypeScript now, and I will gladly replace it if I can in the future. I hope tools like quick-lint-js.com/ will continue to evolve in this direction.
Thank you for your well thought out and informative reply. I appreciate you taking the time :)
I'm a big fan of docblocks, which is why I enjoyed your article (and brilliant reply) to my comment so much. If you look at my work, you'll find plenty of docblocks. I practise document driven development (DDD) so it's a no-brainer. The only way you and I differ here is that I use a type system to document my types and docblocks to document my implementation.
I trust that you know what you know. Please trust me in return when I say that you're making my point for me here:
Out of the box, CRA doesn't skip type checking. I'm also pretty sure that it uses
tsc
to transpile TS > JS. TypeScript isn't slower than JavaScript when you built with CRA because it takes longer to transpile. It's slower becausetranspileOnly
is set tofalse
, so types are being checked.With that in mind, your slide screenshot isn't making a fair comparison because it's comparing apples to apples and oranges (where oranges = static type checking). I guarantee you that if you configured CRA to skip type checking, there wouldn't be such a large discrepancy between the two.
I say this as seasoned Webpack user (CRA without the abstraction) who's both transitioned projects from JavaScript to TypeScript and from Webpack to Vite. My initial experience with TypeScript and Webpack aligns with your experience with CRA. Build times were off the hook. That's when I learned that type checking is a laborious process and all that was needed to speed up the build was to skip this step.
Even without your and my extensive knowledge of the dark arts (that's what how I refer to build process configuration) everybody will see drastic results switching from CRA/Webpack to Vite. It's much faster out of the box because it transpiles with
esbuild
instead oftsc
, and Vite skips type checking by default (emphasis mine):This is what I mean when I say it's comparing apples to apples and oranges yeah? This documentation is spot on to say that we should consider type checking as a separate step from build, because they are totally different things.
When a file is transpiled, it's only concerned with itself and its direct dependencies. When a file is type checked, it's concerned with every dependency in the graph. It's the difference between touching one file and
n
files which is why it's slower.From the same docs page:
If you look at Vite starter templates, their
package.json
provides this script for builds:Now a
production
build takes many times longer to complete due to the type checking stage, but it also won't build if there are type errors. This means you can reduce the likelihood of misused types inproduction
, which (as far as I know) you can't achieve without static type analysis.My point is that you want your
production
build to take as long as possible, performing any and all checks possible to minimise the risk of catastrophic failure. Going back to your screenshot, if deploying toproduction
results in downtime, then instead of avoiding long running tasks, switch to a different deployment method like blue green deployments, or containerisation or similar. That is, build your system outside of your operating environment and only deploy the built files upon success.I'm curious to know what the equivalent of overloading a function would be in docblock:
That is to say,
a
is always a number,b
is a string unlessc
is provided, in which case it's a number.So calling
someFunction(1, 'string', {})
should show an error:Similarly, within the function body itself I would see errors:
b
is undefined it would give me an error if I try to usec
as a recordc
is defined it would give me error if I try to useb
as a stringObviously, this is a contrived example, but it's not an uncommon pattern to encounter in a less abstract way in the wild. I don't think this is possible to achieve with JSDoc alone:
Everything that's returned from this function has the type
number | string | Record<string, string>
which makes the annotation kind of pointless. This is what the types should be:If there's a way to achieve this with JSDoc, I'd love to know more about it. Perhaps this can be achieved with Closure syntax, which I've never used.
I'd never tell someone what tools they should or shouldn't use, and I really hope that this discussion is coming across as informative and not confrontational.
I'm not trying to convince you to use or not use TypeScript or suggest that you're entirely wrong. I just want you to know that transpiling TypeScript is not slower than JavaScript. Type checking is the slow part, and it's really only necessary when integrating your change upstream :)
And again, thanks for your great reply :)
Hello @teamradhq !
Cool that you also like JSDoc!
Thanks for providing such a detailed guide on how type checking works during the build! I hope everyone reading this article will also go through the comments since there is a lot of useful information here.
Regarding react-create-app, even if it's deprecated and everyone prefers Vite now, it is still used in many old projects. Actually, I've been a react-create-app hater since its creation, always preferring to configure Webpack myself, or at least eject the react-create-app to have control over my app's build. Disabling type checking during build is usually the first thing I did. But the problem is not everyone is as curious as we are. Unfortunately, many still use the "standard" react-create-app, where type checking happens before the build. Although this has become less common lately because Vite is doing its job 👍
To be honest, I try not to use overloads in production applications. In applications, I find it better to use multiple functions. Overloads, in my opinion, are more suitable for libraries.
If anything, I'm not making excuses 😄 You can create overloads with JSDoc just as conveniently as in TypeScript using the
@overload
tag. You can learn more about it here - devblogs.microsoft.com/typescript/...Example:
I completely understand and agree with you! However, not everyone grasps this concept, and that's the gist of my article. Everything described in the first paragraph. I have to work with many teams, and each has its reasons for adopting or not adopting TypeScript. I'm just highlighting that going all-in with TypeScript (using .ts files) is not the sole solution to type checking in a project. Action is needed, not just praying to the TypeScript-God!
Thank you so much for your comments! I'm sure they added value to the article!
Thank you for the article! Interesting insight
You don't need a complete transition to TS from JS. Every JS code is valid TS code. So you can migrate your code partially if you want to.
Hey @disane !
Yes, you’re right! That's also one option. However, now you need to add a build step to your delivery-process. Additionally, depending on your development setup, you might encounter issues importing TS files into JS files. With the use of JSDoc, you don't need any of this since it's just comments.