Types with JSDoc is a set of examples showing how JavaScript projects can get strong editor support and type checking without converting every file to TypeScript.

It matches the way this site is built: JavaScript with checkJs, JSDoc annotations, and generated types where they help.

Why it matters

Typed JavaScript is a practical middle ground for existing codebases. It improves tooling and correctness while keeping the authoring model lightweight.

Full documentation, synced from the package README:

Experimentation repo for various ways to type react apps.

See ./src folder for examples

Globally enable TS checking

To enable TS to run everywhere use the js/ts.implicitProjectConfig.checkJS setting in your VScode workspace or user settings.

"js/ts.implicitProjectConfig.checkJs": true

Typescript ignore errors

Pro-tip: CLI tool to automatically add ignore comments

The //@ts-ignore tells TypeScript to ignore the TypeScript errors in the line following the comment.

function mapValues(object, mapFunction) {
  // @ts-ignore
  return Object.fromEntries(Object.entries(object).map(([key, value]) => [key, mapFunction(value)]))
}

This //@ts-expect-error will ignore any typechecking failures in the next line, but will fail the typecheck if there are no errors

function mapValues(object, mapFunction) {
  //@ts-expect-error
  return Object.fromEntries(Object.entries(object).map(([key, value]) => [key, mapFunction(value)]))
}

Ignoring multiple lines

// @ts-ignore-start
// @ts-ignore-end

Nuclear option to disable in file

// @ts-nocheck

Examples

• A bunch of examples https://github.com/voxpelli/types-in-js/discussions/11
• https://github.com/wooorm/dead-or-alive/blob/main/lib/index.js
• https://github.com/Rich-Harris/devalue
• https://github.com/meduzen/datetime-attribute
• https://github.com/geut/deluge/blob/main/src/deluge.js#L1-L29
• https://github.com/ds300/lazyrepo/
• https://github.com/sveltejs/kit/

Resources & Articles

• JSDoc typings: all the benefits of TypeScript, with none of the drawbacks + giltayar/jsdoc-typing
• Tips and tricks for working with types in JavaScript. voxpelli/types-in-js
• JSDoc Cheatsheet
• JSDoc Cheatsheet and Type Safety Tricks on Joshua's Docs
• JSDoc Cheatsheet by Jacob Paris
• jsdoc-examples: Examples of using JSDoc to document JavaScript
• Documentation and JSDoc
• brettz9/awesome-jsdoc: A list of awesome jsdoc tools, resources, etc.
• TSConfig.json reference
• Understand the use of JSDoc through code
• JSDoc & React. JSDoc is very versatile tool. It… | by Anton Krinitsyn | Medium
• jsdoc-templates-demo: demo of well-known jsdoc3 templates & examples
• Check your JS with TS
• JSDoc & React
• TypeScript-JSDoc-Guides
• https://dev.to/t7yang/type-safety-in-javascript-with-jsdoc-and-vscode-1a28
• https://medium.com/@antonkrinitsyn/jsdoc-generic-types-typescript-db213cf48640
• TypeScript without TypeScript -- JSDoc superpowers
• BeyondCodeBootcamp/jsdoc-typescript-starter: getting the most from JSDoc + tsserver (Type Linting without TypeScript)
• https://github.com/simone-sanfratello/do-typescript-without-typescript + https://www.youtube.com/watch?v=xLDVfBUgD8U
• TypeScript Without Transpilation
• もう TypeScript の補助輪を外そう 明日は//@ts-check を使う
• JSDoc: TypeScript inside JavaScript and not the other way around 🤯
• Type Safe JavaScript with JSDoc
• switch to using the "default export" to appease tsserver
• Utilise JSDoc comment tags so that VSCode intellisense works great!
• JSDoc Crash Course 2021
• https://github.com/ipfs/aegir/blob/master/md/ts-jsdoc.md
• andreidmt/tpl-ts-jsdoc: Plain JavaScript with types by leveraging TypeScript's JSDoc support.
• https://github.com/stereobooster/type-o-rama
• TypeScript Type Safety with AJV Standalone + https://github.com/rehanvdm/ajv-standalone-type-saftey
• Highest Voted 'jsdoc' Questions - Stack Overflow
• Types in JavaScript With Zod and JSDoc

Tools

Doc parsers

• https://github.com/ccontrols/structured-types
• https://github.com/yashag/jsdoctor/
• https://github.com/jsdoc-type-pratt-parser/jsdoc-type-pratt-parser
• https://github.com/hegemonic/catharsis
• https://github.com/jsdoctypeparser/jsdoctypeparser
• https://github.com/reactjs/react-docgen
• https://github.com/syavorsky/comment-parser
• https://api-extractor.com/pages/tsdoc/tag_example/
• https://github.com/eslint/doctrine
• https://github.com/DavidWells/jsdoc-parser - Updated fork of dox
• https://github.com/jonschlinkert/parse-comments Parse JavaScript code comments.
• https://github.com/jonschlinkert/tokenize-comment
• https://github.com/jsdoc2md/jsdoc-api - A programmatic interface for jsdoc3 with a few extra features

Formatters

• hosseinmd/prettier-plugin-jsdoc: A prettier plugin for formatting Jsdoc.
• Prettier for JSdoc

Conversion tools

• https://transform.tools Transform lots of stuff!
• https://github.com/vega/ts-json-schema-generator or https://github.com/horiuchi/dtsgenerator TypeScript d.ts file generator from JSON Schema file
• https://github.com/YousefED/typescript-json-schema
• https://github.com/LinbuduLab/json-to-type-graphql JSON / Object / Request ---> TypeGraphQL Class!
• https://github.com/develar/ts2jsdoc - Generate JSDoc from Typescript
• Object to schema https://github.com/unjs/untyped
• Generate TS types from SQL schema https://github.com/vramework/schemats
• Generate TS types from JSON responses https://github.com/ThePrimeagen/undefined
• https://github.com/rmp135/sql-ts Generate TypeScript interfaces from a SQL database.
• OpenAPI to TS https://github.com/drwpow/openapi-typescript
• Generate type.d from openapi spec https://github.com/sigoden/openapi/tree/main/packages/typegen-openapi
• protocol buffer messages to TS https://github.com/thesayyn/protoc-gen-ts
• Protobuff to JSON schema https://github.com/devongovett/protobuf-jsonschema
• Convert TS to flow https://github.com/zxbodya/flowts/blob/master/packages/tsflow/src/convertToFlow.ts
• Typescript for CSS modules https://github.com/mrmckeb/typescript-plugin-css-modules
• JS doc to json schema https://github.com/brettz9/jsdoc-jsonschema
• https://github.com/Surnet/swagger-jsdoc + https://github.com/ajmnz/swagger-jsdoc-indent - Generates swagger/openapi specification based on jsDoc comments and YAML files.
• https://github.com/stereobooster/type-o-rama Directory of conversion tools
• https://github.com/quicktype/quicktype - Generate types and converters from JSON, Schema, and GraphQL
• TS to JS with JSdoc
• JSON to JSDoc
• https://github.com/unjs/untyped
• GraphQL to JSONSchema https://github.com/charlypoly/graphql-to-json-schema
• https://github.com/nijikokun/generate-schema Convert JSON Objects to MySQL, JSON Schema, Mongoose, Google BigQuery, Swagger
• https://github.com/xiaobebe/extract-typescript-types

Extra imported types

• https://github.com/ThomasAribart/json-schema-to-ts
• https://github.com/krzkaczor/ts-essentials
• https://github.com/millsp/ts-toolbelt
• https://github.com/sindresorhus/type-fest
• https://github.com/Col0ring/types-kit
• https://github.com/alii/typestr
• https://github.com/ghoullier/awesome-template-literal-types
• https://github.com/jrylan/json-schema-typed JSON schema type
• https://github.com/jrylan/http-method-enum HTTP methods as a TypeScript enum.
• https://github.com/jrylan/enum-utils/
• https://github.com/ronami/meta-typing
• https://github.com/piotrwitek/utility-types
• https://github.com/Lucifier129/coproduct
• https://github.com/garronej/tsafe
• https://github.com/g-plane/typed-query-selector typed querySelector and querySelectorAll
• https://github.com/g-plane/type-gymnastics

Doc Generators

• https://github.com/galvez/typejuice
• https://github.com/jsdoc2md/jsdoc-to-markdown#readme
• https://github.com/yashag/jsdoctor A smart jsdoc generator
• https://github.com/documentationjs/documentation
• https://github.com/DavidWells/microsoft-api-documenter-example using @microsoft/api-extractor
  • @microsoft/api-documenter
• https://github.com/TypeStrong/typedoc + https://github.com/panva/oauth4webapi/blob/51866b3d65a7ac92a8811e26e55c320f4828a7fc/package.json#L25
• https://github.com/LinusU/ts-readme-generator
• https://github.com/marijnh/getdocs-ts + https://github.com/marijnh/builddocs

Runtime type checkers

• https://github.com/moltar/typescript-runtime-type-benchmarks#packages-compared
• https://github.com/David-Kunz/derive-type Derive types dynamically by running tests to capture value combinations
• https://github.com/brielov/typed
• https://github.com/grantila/typeconv for https://github.com/grantila/suretype
• https://github.com/druc/intus
• https://github.com/spaceteams/zap validation-first schema library with a functional api
• https://github.com/colinhacks/zod/
  • https://github.com/fabien0102/ts-to-zod + https://github.com/alii/azs
• Tiny zod https://github.com/davidmdm/myzod
• https://github.com/ianstormtaylor/superstruct
• https://github.com/artalar/rtcad
• https://github.com/skarab42/tson - Type Safe Object Notation & Validation
• https://github.com/pelotom/runtypes
• https://github.com/vedantroy/typecheck.macro
• https://github.com/sindresorhus/is + https://github.com/sindresorhus/ts-extras
• https://github.com/samchon/typescript-json Super-fast Runtime validator (type checker) with only one line
• https://github.com/sindresorhus/ow
• https://github.com/shigma/schemastery
• https://github.com/justinyaodu/caketype
• https://github.com/yona3/typescanner
• https://github.com/rhys-vdw/ts-auto-guard
• https://github.com/imbrn/v8n
• https://github.com/d-kimuson/type-predicates-generator
• https://github.com/milesj/optimal
• https://github.com/jquense/yup
• https://github.com/sideway/joi
• https://github.com/drummer1992/sito
• https://github.com/vitalets/micro-schema
• https://github.com/daniel7grant/dvali
• https://github.com/crinklesio/schemas
• https://github.com/facebook/prop-types
• https://github.com/elierotenberg/typed-assert
• https://github.com/suchipi/serializable-types
• https://github.com/gcanti/io-ts
• https://github.com/thenativeweb/typedescriptor
• https://github.com/thenativeweb/ensurethat
• https://github.com/thenativeweb/formats
• https://github.com/suchipi/pheno
• https://github.com/markwylde/vamlid - A simple way to validate an object against a pure javascript schema.

VScode extensions

• https://github.com/Perkovec/JSDocLivePreview
• https://github.com/zachhardesty7/jsdoc-comment-toggler/blob/master/src/extension.ts

Msc

• @jitl/ts-simple-type - provides a simple, type-safe API for analyzing types, constructing new types, and generating code based on types.
• typesync Install missing TypeScript typings for dependencies in your package.json.
• type-coverage A CLI tool to check type coverage for typescript code
• typescript-error-reporter-action GitHub Action to diagnose TypeScript errors and report the result on PR.
• A type detection utility for JavaScript https://github.com/sapphiredev/type / https://github.com/pkdev08/klasa-v13/blob/master/src/lib/util/Type.js
• Zod to TS https://github.com/sachinraja/zod-to-ts
• eslint config https://github.com/Agoric/agoric-sdk/blob/20c4ff00adbffff067858c3c5702ae7a9e0522b8/packages/eslint-config/eslint-config.json + https://github.com/homer0/packages/tree/main/packages/personal/eslint-plugin
• https://github.com/benawad/gen-env-types - Generate a .d.ts and .env.example file from your .env file
• Converts from JSON Schema to JSDoc https://github.com/n3ps/json-schema-to-jsdoc or https://github.com/mizuka-wu/json-schema-to-jsdoc/blob/master/src/plugins/jsonschema2jsdoc.js
• https://github.com/livingdocsIO/microschema Small library without dependencies to create JSON Schemas.
• https://github.com/stereobooster/type-o-rama
• https://github.com/johnthecat/babel-plugin-jsdoc-runtime-typecheck/
• https://github.com/heavenshell/ts-lehre
• Clean theme https://github.com/cdaringe/jsdock
• https://github.com/homer0/jsdoc-ts-utils/
• https://github.com/vytenisu/npm-dts Generate index.d.ts file
• Remove typescript types https://github.com/cyco130/detype
• Babel traverse mobx to jsdoc https://github.com/Feverqwe/mst-jsdoc-gen/blob/master/getJsDoc.js
• https://github.com/zacanger/jsdoctap Test runner for doctests using JSDoc examples and node-tap. or https://github.com/TechQuery/test-example/blob/master/source/TestFile.js OR https://github.com/kiwicopple/doctest-js
• Tool to generate a single bundle of dts https://github.com/timocov/dts-bundle-generator
• https://github.com/garbles/json-schema-multi-compiler
• https://github.com/json-schema-faker/json-schema-faker
• https://github.com/typescript-cheatsheets/react
• https://github.com/gendocu-com/grpc-docs - Interactive gRPC API Documentation
• https://github.com/2fd/graphtype Generate TypeScripts definitions from GraphQL
• https://github.com/rawrmaan/restyped End-to-end typing for REST APIs with TypeScript
• https://github.com/etienne-dldc/zensql A Typescript type-safe SQL system
• https://github.com/Ff00ff/mammoth A type-safe Postgres query builder for TypeScript.
• https://github.com/JoshuaKGoldberg/TypeStat Converts JavaScript to TypeScript and TypeScript to better TypeScript.
• https://github.com/airtasker/spot Write API as code and generate other API contract formats (OpenAPI, Swagger, JSON Schema)
• https://github.com/readmeio/oas Easily create and manage OpenAPI Documents via code comments
• https://github.com/Akryum/vue-typegen scan components and generate types
• https://github.com/deanshub/data-from-types generates data from TypeScript types
• https://github.com/chasefleming/enum-xyz Enums in vanilla JS via proxy
• https://github.com/apidoc/apidoc RESTful web API Documentation Generator.
• https://github.com/twentyfourg/jest-apidoc Generate api docs from jest tests
• https://github.com/thenativeweb/is-typescript Check if project is typescript
• https://github.com/suchipi/convert-to-dts

Examples

• https://github.com/Ethan-Arrowood/lego-world-map-designer/blob/main/index.js
• https://gitlab.com/jugglinmike/friend-off/-/blob/main/src/server/room.js
• https://github.com/Kr1an/react-jsdoc-sample + https://github.com/Kr1an/jsdoc-react-express-sample/blob/master/src/Single.js
• https://github.com/wooorm/f-ck
• https://github.com/micromark/micromark/blob/edbfa7a2d358d3264bd4524e947698cd7f7b480f/packages/micromark-util-types/index.js
• https://github.com/fenomas/noa/blob/master/src/index.js
• https://github.com/apollographql/apollo-server/issues/5097#issuecomment-822867819 + https://github.com/jaydenseric/graphql-upload/blob/master/package.json
• https://github.com/MrShoenel/orchestration-tools + https://mrshoenel.github.io/orchestration-tools/
• https://github.com/rubengomex/js-spotify-api/blob/master/src/index.js
• https://github.com/homer0/parserror/blob/c12b20e3a321e1e01f41178eceb1d3210991d40f/src/parserror.js#L240
• https://github.com/knockaway/loan-calculator/blob/master/lib/calculate-apr.js#L5-L19

Using test code for docs

• https://github.com/linear/linear/blob/bc39d23af232f9fdbe7df458b0aaa9554ca83c57/packages/sdk/src/_tests/readme.test.ts#L57-L70
  • https://github.com/linear/linear/blob/94af540244864fbe466fb933256278e04e87513e/docs/markdown-magic.config.js + https://github.com/linear/linear/blob/94af540244864fbe466fb933256278e04e87513e/docs/transforms/code-section.js
• Pull in sub sections of markdown to other files https://github.com/linear/linear/blob/93981d3a3db571e2f8efdce9f5271ea678941c43/packages/codegen-doc/README.md#L32
• https://github.com/linear/linear/blob/93981d3a3db571e2f8efdce9f5271ea678941c43/docs/transforms/text-section.js + https://github.com/linear/linear/blame/bc39d23af232f9fdbe7df458b0aaa9554ca83c57/README.md#L42

Links

• GitHub repository