Description
openedon Nov 30, 2019
Previously: #17014
While Gutenberg packages are not authored in TypeScript, we can still benefit from its JavaScript type checking using the JSDoc we already write. This will bring us some benefit of type safety, even as we continue to write modules with JavaScript, not TypeScript.
Progress:
All of our modules are to be opted-in to type checking. The progress thus far:
- a11y (A11y: Add types #19096)
- annotations
- api-fetch
- autop (Packages: Add and check types #20669)
- babel-plugin-import-jsx-pragma
- babel-plugin-makepot
- babel-preset-default
- base-styles
- blob (Blob: Add types #19092)
- block-directory
- block-editor (Block Editor: Add type-checking for block editor (DOM utils only) #21362, ...)
- block-library
- block-serialization-default-parser
- block-serialization-spec-parser
- blocks
- browserslist-config
- components
- compose (
Compose: Add types #21580Compose: Add types (progressively) #27344) - core-data
- create-block
- custom-templated-path-webpack-plugin
- data
- data-controls
- date date: Add types #29789
- dependency-extraction-webpack-plugin (Dependency Extraction Webpack Plugin: Add types #22498)
- deprecated (Deprecated: Type package #26429)
- docgen
- dom (split into multiple smaller PRs)
- dom-ready (Dom Ready: Add types #19089)
- e2e-test-utils
- e2e-tests
- edit-post
- edit-site
- edit-widgets
- editor
- element
- first pass (Element: Add types #21248)
- needs work after Types: Hide element, primitives, icons declarations #21613
- use stricter types config
- env
- escape-html (Packages: Add and check types #20669)
- eslint-plugin
- format-library
- hooks (Hooks: Type package #26430)
- html-entities (Packages: Add and check types #20669)
- i18n (i18n: Add types #19099)
- interface
- icons (Icons: Add types #21487, Types: Hide element, primitives, icons declarations #21613, Types: Restore element, icons, primitives types #21781)
- is-shallow-equal (Is Shallow Equal: Add types #19090)
- jest-console
- jest-preset-default
- jest-puppeteer-axe
- keyboard-shortcuts
- keycodes (Keycodes: Add, enhance types #19520)
- library-export-default-webpack-plugin
- list-reusable-blocks
- media-utils
- notices
- npm-package-json-lint-config
- nux
- plugins
- postcss-themes
- prettier-config (Prettier Config: Add type-checking #21053)
- primitives (Primitives: Add types #21482, Types: Hide element, primitives, icons declarations #21613, Types: Restore element, icons, primitives types #21781)
- priority-queue (Priority Queue: Enable types with enhanced JSDoc type details #18997)
- project-management-automation (Project Management Automation: Add TypeScript type-checking #20850)
- redux-routine (Redux routine: Add types #21313)
- rich-text
- scripts
- server-side-render
- shortcode
- token-list (Token List: Add type checking #18839)
- url (chore(url): add jsdoc typescript checking #17014)
- viewport
- warning (Add warning package #19317)
- wordcount (WordCount: Add types #22077)
Guidelines:
See the packages README for details on TypeScript usage. In summary, a package can opt-in by following these steps:
- Add a
tsconfig.json
to the package root. The@wordpress/i18n
package has a good example of a basic config. - Add
"types": "build-types"
to the package'spackage.json
so that consumers will pick up the published types from the package. - Add the package to the root
tsconfig.json
references
.
For single files, you can also include a // @ts-check
line at the top of the file. You should use this line when temporarily testing the impact of type checking, or if you are working to convert a very large package one file at a time.
The build:package-types
npm script will be run as part of precommit, which handles type checking. It can be very helpful to watch the types build and work through issues surfaced by the compiler as you add types. To watch the types build, run:
npm run build:package-types -- --watch
You may also need to improve existing JSDoc, as it was written based on assumed usage. Type checking will enforce its validity, and in many cases our JSDoc is invalid.
For syntax and usage, reference:
- https://github.com/WordPress/gutenberg/blob/master/docs/contributors/coding-guidelines.md#javascript-documentation-using-jsdoc
- https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/
- https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
- https://jsdoc.app/