voxpelli/types-in-js

Tips and tricks for working with types in JavaScript

Types in JavaScript

If you love types but not transpiling, then using TypeScript itself won't be your cup of tea, but there are other approaches you can take to get pretty close.

Participate

Join our GitHub discussions!

This repo exists mainly to promote a discussion around this topic – exchange experiences, share best practices and tips and ask for help on tricky parts. The discussions is found in the GitHub discussions of this repo

Is there a readme badge?

Yes! If you use types in plain JS in your project, you can include thise badge in your readme to let people know that your code is typed without relying on TypeScript syntax.

[![Types in JS](https://img.shields.io/badge/types_in_js-yes-brightgreen)](https://github.com/voxpelli/types-in-js)

How to use types in JavaScript

TypeScript supports JavaScript and it supports quite a few JSDoc annotations to help you type your JS code (some, like @deprecated, is even used in TS-code).

Since TypeScript is what drives the JavaScript tools in Visual Studio Code and its intellisense the implementation is actually used more than one would initially guess.

Getting started

1. Add a tsconfig.json with eg. allowJs: true or add a jsconfig.json instead, which implies allowJs: true (Turns out that jsconfig.json implies a lot more than just allowJs: true and as such is not recommended. See discussion at #25)

2. Then point it to your javascript files by using files and/or include properties.

3. Lastly either set checkJs: true in it, to have all of those files checked, or selectively add // @ts-check to the top of the files you want to check.

4. (optional) Add some other useful / needed configurations, see TSConfig tips.

5. (optional) Install typescript locally in your project (npm install typescript), then validate your project using npx tsc (tsc is the name of the CLI supplied by typescript). tsc can preferably be run as a part of your test scripts, locally and on CI. See CI / linting tips

Articles around using types with JavaScript

• TypeScript without TypeScript -- JSDoc superpowers by @ddprrt

TSConfig tips

See open discussion as well as base configs to extend from.

CI / linting / additional tools

See open discussion

JSDoc syntax tips

There's a cheatsheet available

Managing third party dependencies

See open discussion

Other good resources

• DavidWells/types-with-jsdocs
• TypeScript JSDoc Reference