Closed swyxio closed 2 years ago
I like the approach with JSDoc, compared to Typescript it is less restricted therefore seems easier to handle. I recently switched for SvelteKit development from Typescript to JSDoc, initiated by reading your blog post a couple of weeks ago. Thanks for sharing your idea / this post.
thanks for the comment!
image: https://user-images.githubusercontent.com/6764957/152372196-ded316b8-3111-4690-bb71-1fc801d2c471.png slug: jsdoc-swyxkit category: tutorial canonical_url: https://swyxkit.netlify.app/how-to-add-jsdoc-typechecking-to-sveltekit
As I build out swyxkit, I am finding that I am no longer prototyping and that I need to be able to refactor with confidence.
This makes it the right time to introduce types!
I was tempted to use TypeScript since I am more familiar with that, but since SvelteKit is written with JSDoc types, I figured I'd finally give that a try as I had never tried it before.
Verdict
You can see my successful conversion attempt here: https://github.com/sw-yx/swyxkit/pull/23/
I'm pleased to report that I think JSDoc Typechecking is a perfect match for light-logic projects like this blog starter - when you don't want to slow your builds down to strip out types, and you don't REALLY need to strictly typecheck every little thing. IMO you should basically aim to typecheck just the riskiest parts of your code, which are mostly function boundaries, API responses and non-string values like Date.
The whole process took me about 30 mins and I already found myself experiencing the benefits of typechecking as I tweaked the return signatures of some functions and changed the props of some components (amazing work by @dummdidumm who maintains the Svelte Language Server - it can even detect when required props are missing!)
What follows here is an intro to Just Enough JSDoc Typechecking so you can get going with this on your own project.
Step 1: Simple variable declaration typing
The most basic jsdoc typing you can do is typing variable declarations. Since JS does implicit string conversion, I think you get the most mileage out of typing any component prop that isn't a string.
This just helps prevent ugly unintended stringification.
The SvelteKit docs also strongly encourage you to annotate the SvelteKit APIs in pages:
and API routes:
Of course, most of your data is gonna come with more complex types, which you will need to reuse...
Step 2: Make a
.d.ts
fileYou're going to pull your types, particularly reusable types, from this file. Rich says you should put it in
/src/lib/types.d.ts
so you can take advantage of SvelteKit's aliasing. Stub out your types and build them up as you convert the rest of the files...Step 3: Imported typing for variable declaration
Now you can annotate more complex component props:
that wasn't too bad! Go through all your Svelte files and annotate; you'll probably find that you will need to flesh out your
.d.ts
file types as you go. However, you'll still need to annotate API responses for full safety...Step 4: Typing Node.js functions
Node.js code probably has the strongest reasons to properly annotate functions since this has the most data risk - you wanna be warned any time the type signature of inputs or outputs change. Here's how to do it:
If you are parsing data and just need to annotate inline functions, that's possible too:
Date sorting needs a bit of special love and care:
Step 5: Run your code!
You can do steps 1-4 entirely in the editor, relying on the language server, but the real test of whether or not you broke anything is just running your code. I caught two big mistakes in my refactor, mostly to do with not properly typing my API responses.
Further reading