From 88a253a2861651d264e7f8436cc4400735229c6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Tammerg=C3=A5rd?= Date: Fri, 15 May 2026 16:15:49 +0200 Subject: [PATCH] Remove migration cheat sheet --- .../ISSUE_TEMPLATE/migrating-cheatsheet.md | 15 -- README.md | 12 +- docs/advanced/index.md | 3 +- docs/advanced/misc-concerns.md | 24 +-- docs/advanced/patterns_by_version.md | 4 +- docs/advanced/utility-types.md | 2 - docs/basic/recommended/codebases.md | 1 - docs/basic/recommended/resources.md | 2 +- docs/basic/troubleshooting/learn-ts.md | 1 - docs/basic/troubleshooting/types.md | 6 - docs/migration/from-flow.md | 15 -- docs/migration/from-js.md | 110 ------------- docs/migration/index.md | 145 ------------------ docs/migration/js-docs.md | 16 -- website/docusaurus.config.js | 4 - website/sidebars.json | 6 - 16 files changed, 6 insertions(+), 360 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/migrating-cheatsheet.md delete mode 100644 docs/migration/from-flow.md delete mode 100644 docs/migration/from-js.md delete mode 100644 docs/migration/index.md delete mode 100644 docs/migration/js-docs.md diff --git a/.github/ISSUE_TEMPLATE/migrating-cheatsheet.md b/.github/ISSUE_TEMPLATE/migrating-cheatsheet.md deleted file mode 100644 index 2a3dde110..000000000 --- a/.github/ISSUE_TEMPLATE/migrating-cheatsheet.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: Migrating Cheatsheet -about: Report Issue/Suggest an idea for Migrating Cheatsheet -title: "[Migrating] ISSUE_TITLE_HERE" -labels: MIGRATING -assignees: "" ---- - -**What cheatsheet is this about? (if applicable)** - -Migrating cheatsheet - -**What's your issue or idea?** - -_Write here_ diff --git a/README.md b/README.md index 7e45eea5f..b7c63aa02 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,6 @@ Cheatsheet for using React with TypeScript. - It also has miscellaneous tips and tricks for pro users. - Advice for contributing to DefinitelyTyped. - The goal is to take _full advantage_ of TypeScript. -- [The Migrating Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/migration) helps collate advice for incrementally migrating large codebases from JS or Flow, **from people who have done it**. - - We do not try to convince people to switch, only to help people who have already decided. - - ⚠️This is a new cheatsheet, all assistance is welcome. - [The HOC Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/hoc) specifically teaches people to write HOCs with examples. - Familiarity with [Generics](https://www.typescriptlang.org/docs/handbook/2/generics.html) is necessary. - ⚠️This is the newest cheatsheet, all assistance is welcome. @@ -2433,8 +2430,6 @@ npm install -g dts-gen dts-gen -m ``` -There are other automated JS to TS conversion tools and migration strategies - see [our MIGRATION cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/migration/from_js). - ##### Typing Exported Hooks Typing Hooks is just like typing pure functions. @@ -2540,8 +2535,6 @@ declare module "use-dark-mode" { In case of typing untyped class components, there's almost no difference in approach except for the fact that after declaring the types, you export the extend the type using `class UntypedClassComponent extends React.Component {}` where `UntypedClassComponentProps` holds the type declaration. -For instance, [sw-yx's Gist on React Router 6 types](https://gist.github.com/sw-yx/37a6a3d248c2d4031801f0d568904df8) implemented a similar method for typing the then untyped RR6. - ```ts declare module "react-router-dom" { import * as React from 'react'; @@ -2556,8 +2549,6 @@ declare module "react-router-dom" { // ... ``` -For more information on creating type definitions for class components, you can refer to this [post](https://templecoding.com/blog/2016/03/31/creating-typescript-typings-for-existing-react-components) for reference. - #### Frequent Known Problems with TypeScript Just a list of stuff that React developers frequently run into, that TS has no solution for. Not necessarily TSX only. @@ -2943,7 +2934,7 @@ If you're looking for information on Prettier, check out the [Prettier](https:// 9. bangbang checks `if (!!nonboolean)` 10. `!= null` to check for `null` and `undefined` - [Ultimate React Component Patterns with TypeScript 2.8](https://levelup.gitconnected.com/ultimate-react-component-patterns-with-typescript-2-8-82990c516935) -- [Basarat's TypeScript gitbook has a React section](https://basarat.gitbook.io/typescript/tsx/react) with an [Egghead.io course](https://egghead.io/courses/use-typescript-to-develop-react-applications) as well. +- [Basarat's TypeScript gitbook has a React section](https://basarat.gitbook.io/typescript/tsx/react). - [Palmer Group's TypeScript + React Guidelines](https://github.com/palmerhq/typescript) as well as Jared's other work like [disco.chat](https://github.com/jaredpalmer/disco.chat) - [Sindre Sorhus' TypeScript Style Guide](https://github.com/sindresorhus/typescript-definition-style-guide) - [TypeScript React Starter Template by Microsoft](https://github.com/Microsoft/TypeScript-React-Starter) A starter template for TypeScript and React with a detailed README describing how to use the two together. Note: this doesn't seem to be frequently updated anymore. @@ -2993,7 +2984,6 @@ It is worth mentioning some resources to help you get started: - Anders Hejlsberg's overview of TS: https://www.youtube.com/watch?v=ET4kT88JRXs - Marius Schultz: https://blog.mariusschulz.com/series/typescript-evolution with an [Egghead.io course](https://egghead.io/courses/advanced-static-types-in-typescript) - Basarat's Deep Dive: https://basarat.gitbook.io/typescript/ -- Axel Rauschmeyer's [Tackling TypeScript](https://exploringjs.com/tackling-ts/) - Rares Matei: [Egghead.io course](https://egghead.io/courses/practical-advanced-typescript)'s advanced TypeScript course on Egghead.io is great for newer typescript features and practical type logic applications (e.g. recursively making all properties of a type `readonly`) - Learn about [Generics, Conditional types and Mapped types](https://www.youtube.com/watch?v=PJjeHzvi_VQ&feature=youtu.be) - Shu Uesugi: [TypeScript for Beginner Programmers](https://ts.chibicode.com/) diff --git a/docs/advanced/index.md b/docs/advanced/index.md index a6424d6aa..af3a48dd3 100644 --- a/docs/advanced/index.md +++ b/docs/advanced/index.md @@ -12,10 +12,9 @@ title: Advanced Cheatsheet **Creating React + TypeScript Libraries** -The best tool for creating React + TS libraries right now is [`tsdx`](https://github.com/palmerhq/tsdx). Run `npx tsdx create` and select the "react" option. You can view [the React User Guide](https://github.com/palmerhq/tsdx/issues/5) for a few tips on React+TS library best practices and optimizations for production. +The best tool for creating React + TS libraries right now is [`tsdx`](https://github.com/palmerhq/tsdx). Run `npx tsdx create` and select the "react" option. Another option is [Rollpkg](https://github.com/rafgraph/rollpkg), which uses Rollup and the TypeScript compiler (not Babel) to create packages. It includes default configs for TypeScript, Prettier, ESLint, and Jest (setup for use with React), as well as Bundlephobia package stats for each build. -- Be sure to also check [`basarat`'s guide](https://basarat.gitbooks.io/typescript/content/docs/quick/library.html) for library tsconfig settings. - Alec Larson: [The best Rollup config for TypeScript libraries](https://gist.github.com/aleclarson/9900ed2a9a3119d865286b218e14d226) - From the Angular world, check out https://github.com/bitjson/typescript-starter diff --git a/docs/advanced/misc-concerns.md b/docs/advanced/misc-concerns.md index fb9839e75..f60462f48 100644 --- a/docs/advanced/misc-concerns.md +++ b/docs/advanced/misc-concerns.md @@ -28,7 +28,7 @@ export class MyComponent extends React.Component { ## Commenting Components -TypeScript uses [TSDoc](https://github.com/Microsoft/tsdoc), a variant of JSDoc for TypeScript. This is very handy for writing component libraries and having useful descriptions pop up in autocomplete and other tooling (like the [Docz PropsTable](https://www.docz.site/docs/components-api#propstable)). The main thing to remember is to use `/** YOUR_COMMENT_HERE */` syntax in the line just above whatever you're annotating. +TypeScript uses [TSDoc](https://github.com/Microsoft/tsdoc), a variant of JSDoc for TypeScript. This is very handy for writing component libraries and having useful descriptions pop up in autocomplete and other tooling. The main thing to remember is to use `/** YOUR_COMMENT_HERE */` syntax in the line just above whatever you're annotating. ```tsx interface MyComponentProps { @@ -87,26 +87,6 @@ For developing with Storybook, read the docs I wrote over here: [https://storybo [Something to add? File an issue](https://github.com/typescript-cheatsheets/react/issues/new). -## Migrating From Flow - -You should check out large projects that are migrating from flow to pick up concerns and tips: - -- [Jest](https://github.com/facebook/jest/pull/7554) -- [Expo](https://github.com/expo/expo/issues/2164) -- [React-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd/issues/982) -- [Storybook](https://github.com/storybooks/storybook/issues/5030) -- [VueJS](https://medium.com/the-vue-point/plans-for-the-next-iteration-of-vue-js-777ffea6fabf) - -Useful libraries: - -- [https://github.com/bcherny/flow-to-typescript](https://github.com/bcherny/flow-to-typescript) -- [https://github.com/Khan/flow-to-ts](https://github.com/Khan/flow-to-ts) -- [https://github.com/piotrwitek/utility-types](https://github.com/piotrwitek/utility-types) - -If you have specific advice in this area, please file a PR! - -[Something to add? File an issue](https://github.com/typescript-cheatsheets/react/issues/new). - ## Prettier There isn't any real secret to Prettier for TypeScript. But its a great idea to run prettier on every commit! @@ -144,7 +124,7 @@ $ yarn add -D prettier husky lint-staged Integrating this with ESlint may be a problem. We haven't written much on this yet, please contribute if you have a strong opinion. [Here's a helpful gist.](https://gist.github.com/JirkaVebr/519c7597517e4ba756d5b89e7cb4cc0e) -For library authors, this is set up for you in [tsdx](https://github.com/palmerhq/tsdx/pull/45/files). You may also wish to check out the newer https://ts-engine.dev/ project. +For library authors, this is set up for you in [tsdx](https://github.com/palmerhq/tsdx/pull/45/files). ## Testing diff --git a/docs/advanced/patterns_by_version.md b/docs/advanced/patterns_by_version.md index 021e77bce..3bd67e1c6 100644 --- a/docs/advanced/patterns_by_version.md +++ b/docs/advanced/patterns_by_version.md @@ -10,7 +10,7 @@ _TypeScript version guides before 2.9 are unwritten, please feel free to send a ## TypeScript 2.9 -[[Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-9.html) | [Blog Post](https://blogs.msdn.microsoft.com/typescript/2018/05/31/announcing-typescript-2-9/)] +[[Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-9.html)] 1. Type arguments for tagged template strings (e.g. `styled-components`): @@ -568,5 +568,3 @@ nothing react specific ## TypeScript Roadmap and Spec https://github.com/Microsoft/TypeScript/wiki/Roadmap - -Did you also know you can read the TypeScript spec online?? https://github.com/microsoft/TypeScript/blob/master/doc/spec-ARCHIVED.md diff --git a/docs/advanced/utility-types.md b/docs/advanced/utility-types.md index c50018a6d..55150dc86 100644 --- a/docs/advanced/utility-types.md +++ b/docs/advanced/utility-types.md @@ -8,8 +8,6 @@ We will assume knowledge of utility types covered in the sister project [`typesc If you intend to maintain a large TS codebase/a nontrivial React+TS library, **we strongly recommend exploring these utilities** so that you don't reinvent the wheel and/or lose sanity trying to do so. Studying their code can also teach you a lot of advanced TS that is not covered here. -I also recommend having a good working knowledge of how to construct the inbuilt utility types from scratch. See [Dr. Rauschmayer's guide](https://2ality.com/2020/06/computing-with-types.html) for a concise introduction. - A level of comfort with **generic types** is therefore required. Here are some helpful resources: - https://ts.chibicode.com/generics/ diff --git a/docs/basic/recommended/codebases.md b/docs/basic/recommended/codebases.md index 440e9a74d..f80c2d786 100644 --- a/docs/basic/recommended/codebases.md +++ b/docs/basic/recommended/codebases.md @@ -27,7 +27,6 @@ sidebar_label: Codebases Older but still worth checking: - https://bitbucket.org/atlassian/atlaskit-mk-2/src/master/ -- https://github.com/contiamo/operational-ui React Boilerplates: diff --git a/docs/basic/recommended/resources.md b/docs/basic/recommended/resources.md index 476e47c15..967cb3b93 100644 --- a/docs/basic/recommended/resources.md +++ b/docs/basic/recommended/resources.md @@ -19,7 +19,7 @@ sidebar_label: Other resources 9. bangbang checks `if (!!nonboolean)` 10. `!= null` to check for `null` and `undefined` - [Ultimate React Component Patterns with TypeScript 2.8](https://levelup.gitconnected.com/ultimate-react-component-patterns-with-typescript-2-8-82990c516935) -- [Basarat's TypeScript gitbook has a React section](https://basarat.gitbook.io/typescript/tsx/react) with an [Egghead.io course](https://egghead.io/courses/use-typescript-to-develop-react-applications) as well. +- [Basarat's TypeScript gitbook has a React section](https://basarat.gitbook.io/typescript/tsx/react). - [Palmer Group's TypeScript + React Guidelines](https://github.com/palmerhq/typescript) as well as Jared's other work like [disco.chat](https://github.com/jaredpalmer/disco.chat) - [Sindre Sorhus' TypeScript Style Guide](https://github.com/sindresorhus/typescript-definition-style-guide) - [TypeScript React Starter Template by Microsoft](https://github.com/Microsoft/TypeScript-React-Starter) A starter template for TypeScript and React with a detailed README describing how to use the two together. Note: this doesn't seem to be frequently updated anymore. diff --git a/docs/basic/troubleshooting/learn-ts.md b/docs/basic/troubleshooting/learn-ts.md index 89cf12bb4..cdd24feff 100644 --- a/docs/basic/troubleshooting/learn-ts.md +++ b/docs/basic/troubleshooting/learn-ts.md @@ -14,7 +14,6 @@ It is worth mentioning some resources to help you get started: - Anders Hejlsberg's overview of TS: https://www.youtube.com/watch?v=ET4kT88JRXs - Marius Schultz: https://blog.mariusschulz.com/series/typescript-evolution with an [Egghead.io course](https://egghead.io/courses/advanced-static-types-in-typescript) - Basarat's Deep Dive: https://basarat.gitbook.io/typescript/ -- Axel Rauschmeyer's [Tackling TypeScript](https://exploringjs.com/tackling-ts/) - Rares Matei: [Egghead.io course](https://egghead.io/courses/practical-advanced-typescript)'s advanced TypeScript course on Egghead.io is great for newer typescript features and practical type logic applications (e.g. recursively making all properties of a type `readonly`) - Learn about [Generics, Conditional types and Mapped types](https://www.youtube.com/watch?v=PJjeHzvi_VQ&feature=youtu.be) - Shu Uesugi: [TypeScript for Beginner Programmers](https://ts.chibicode.com/) diff --git a/docs/basic/troubleshooting/types.md b/docs/basic/troubleshooting/types.md index 5946605a1..970e32ff5 100644 --- a/docs/basic/troubleshooting/types.md +++ b/docs/basic/troubleshooting/types.md @@ -413,8 +413,6 @@ npm install -g dts-gen dts-gen -m ``` -There are other automated JS to TS conversion tools and migration strategies - see [our MIGRATION cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/migration/from_js). - ### Typing Exported Hooks Typing Hooks is just like typing pure functions. @@ -520,8 +518,6 @@ declare module "use-dark-mode" { In case of typing untyped class components, there's almost no difference in approach except for the fact that after declaring the types, you export the extend the type using `class UntypedClassComponent extends React.Component {}` where `UntypedClassComponentProps` holds the type declaration. -For instance, [sw-yx's Gist on React Router 6 types](https://gist.github.com/sw-yx/37a6a3d248c2d4031801f0d568904df8) implemented a similar method for typing the then untyped RR6. - ```ts declare module "react-router-dom" { import * as React from 'react'; @@ -536,8 +532,6 @@ declare module "react-router-dom" { // ... ``` -For more information on creating type definitions for class components, you can refer to this [post](https://templecoding.com/blog/2016/03/31/creating-typescript-typings-for-existing-react-components) for reference. - ## Frequent Known Problems with TypeScript Just a list of stuff that React developers frequently run into, that TS has no solution for. Not necessarily TSX only. diff --git a/docs/migration/from-flow.md b/docs/migration/from-flow.md deleted file mode 100644 index a7d7f3dbd..000000000 --- a/docs/migration/from-flow.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -id: from_flow -title: From Flow ---- - -- (2022) Try Stripe's [Flow to TS codemod](https://github.com/stripe-archive/flow-to-typescript-codemod): [blogpost](https://stripe.com/blog/migrating-to-typescript), [podcast discussion](https://devtools.fm/episode/33) -- Try flow2ts: `npx flow2ts` - doesn't work 100% but saves some time ([see this and other tips from @braposo](https://github.com/typescript-cheatsheets/react/pull/79#issuecomment-458227322) at TravelRepublic) -- Try [Airtable's codemod](https://github.com/Airtable/typescript-migration-codemod): https://medium.com/airtable-eng/the-continual-evolution-of-airtables-codebase-migrating-a-million-lines-of-code-to-typescript-612c008baf5c -- [Incremental Migration to TypeScript on a Flowtype codebase][entria] at Entria -- [MemSQL's Studio's migration](https://davidgom.es/porting-30k-lines-of-code-from-flow-to-typescript/) - blogpost with many useful tips -- Quick-n-dirty [Flow to TS Codemod](https://gist.github.com/skovhus/c57367ce6ecbc3f70bb7c80f25727a11) -- [Ecobee's brief experience](https://mobile.twitter.com/alanhietala/status/1104450494754377728) -- [Migrating a 50K SLOC Flow + React Native app to TypeScript](https://blog.usejournal.com/migrating-a-flow-react-native-app-to-typescript-c74c7bceae7d) -- [How we migrated 400K+ lines of code from Flow to TypeScript at Factorial](https://labs.factorialhr.com/posts/how-we-migrated-400k-lines-of-code-from-flow-to-typescript) - [entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d "Incremental Migration to TypeScript on a Flowtype codebase" diff --git a/docs/migration/from-js.md b/docs/migration/from-js.md deleted file mode 100644 index dd8cff7c9..000000000 --- a/docs/migration/from-js.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -id: from_js -title: From JS ---- - -## Automated JS to TS Conversion - -- [TypeStat](https://github.com/JoshuaKGoldberg/TypeStat) ([used by Codecademy](https://mobile.twitter.com/JoshuaKGoldberg/status/1159090281314160640)) -- [TypeWiz](https://github.com/urish/typewiz) -- [js-to-ts-converter](https://github.com/gregjacobs/js-to-ts-converter) -- [TS-migrate](https://github.com/airbnb/ts-migrate) used in [Airbnb's conversion](https://medium.com/airbnb-engineering/ts-migrate-a-tool-for-migrating-to-typescript-at-scale-cd23bfeb5cc) -- [dts-gen](https://github.com/microsoft/dts-gen) - `dts-gen` is a tool that generates TypeScript definition files (.d.ts) from any JavaScript object. - -for JSON - http://json2ts.com/ generate TypeScript interfaces from JSON - -## Manual JS to TS Conversion - -the "Just Renaming" strategy - -- OSX/Linux: `find src -name "*.js" -exec sh -c 'mv "$0" "${0%.js}.tsx"' {} \;` - -You can either load typescript files with webpack, or use the `tsc` compiler to compile your TS files to JS side by side. The basic `tsconfig.json` is: - -```json -{ - "compilerOptions": { - "allowJs": true - } -} -``` - -Then you will want to enable it to check JS: - -```json -{ - "compilerOptions": { - "allowJs": true, - "checkJs": true - } -} -``` - -If you have a large codebase and this throws too many errors at once, you can opt out problematic files with `//@ts-nocheck`, or instead turn off `checkJs` and add a `//@ts-check` directive at the top of each regular JS file. - -TypeScript should throw up some egregious errors here which should be easy to fix. - -Once you are done, swallow the red pill by turning off implicit `any`'s: - -```js -{ - "compilerOptions": { - "allowJs": true, - "checkJs": true, - "noImplicitAny": true // or "strict": true - } -} -``` - -This will raise a bunch of type errors and you can start converting files to TS or (optionally) use [JSDoc annotations](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) in your JS. - -A common practice here is using an ambient TODO type alias for `any` so you can keep track of what you need to come back to: - -```ts -type TODO_TYPEME = any; -export function myFunc(foo: TODO_TYPEME, bar: TODO_TYPEME): number { - // ... -} -``` - -Gradually add [more `strict` mode flags](https://www.typescriptlang.org/docs/handbook/compiler-options.html) like `noImplicitThis`, `strictNullChecks`, and so on until you can eventually just run in full strict mode with no js files left: - -```js -{ - "compilerOptions": { - "strict": true - } -} -``` - -## 3 Step Process - -![image](https://user-images.githubusercontent.com/6764957/91499410-f1399080-e8f3-11ea-86f8-431266af713b.png) - -https://speakerdeck.com/amhinson/convert-a-react-native-project-to-typescript-in-10-minutes?slide=23 - -## More resources - -- [Adopting TypeScript at Scale - AirBnB's conversion story and strategy](https://www.youtube.com/watch?v=P-J9Eg7hJwE) - their [ts-migrate tool here](https://medium.com/airbnb-engineering/ts-migrate-a-tool-for-migrating-to-typescript-at-scale-cd23bfeb5cc) -- [Scaling TypeScript lessons from Bloomberg](https://www.techatbloomberg.com/blog/10-insights-adopting-typescript-at-scale/) -- [Migrating a `create-react-app`/`react-scripts` app to TypeScript](https://facebook.github.io/create-react-app/docs/adding-typescript) - don't use `react-scripts-ts` -- [Migrating an EJECTED CRA app to TS](https://spin.atomicobject.com/2018/07/04/migrating-cra-typescript/) -- [Lyft's JS to TS migration tool](https://github.com/lyft/react-javascript-to-typescript-transform) (includes PropTypes migration) -- [Hootsuite][hootsuite] -- [Etsy's Journey to TypeScript](https://codeascraft.com/2021/11/08/etsys-journey-to-typescript/) -- [Storybook's migration (PR)](https://github.com/storybooks/storybook/issues/5030) -- [How we migrated a 200K+ LOC project to TypeScript and survived to tell the story][coherentlabs] - Coherent Labs - using `grunt-ts`, jQuery and Kendo UI -- incrementally adding strict null checks https://code.visualstudio.com/blogs/2019/05/23/strict-null - -Old content that is possibly out of date - -- [Incrementally Migrating JS to TS][clayallsop] (old) -- [Microsoft's TypeScript React Conversion Guide][mstsreactconversionguide] (old) - -[clayallsop]: https://medium.com/@clayallsopp/incrementally-migrating-javascript-to-typescript-565020e49c88 "Incrementally Migrating JavaScript to TypeScript" -[pleo]: https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4 "Migrating a Babel project to TypeScript" -[tiny]: https://go.tiny.cloud/blog/benefits-of-gradual-strong-typing-in-javascript/ "Benefits of gradual strong typing in JavaScript" -[entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d "Incremental Migration to TypeScript on a Flowtype codebase" -[mstsreactconversionguide]: https://github.com/Microsoft/TypeScript-React-Conversion-Guide "TypeScript React Conversion Guide" -[coherentlabs]: https://hashnode.com/post/how-we-migrated-a-200k-loc-project-to-typescript-and-survived-to-tell-the-story-ciyzhikcc0001y253w00n11yb "How we migrated a 200K+ LOC project to TypeScript and survived to tell the story" -[hootsuite]: https://medium.com/hootsuite-engineering/thoughts-on-migrating-to-typescript-5e1a04288202 "Thoughts on migrating to TypeScript" diff --git a/docs/migration/index.md b/docs/migration/index.md deleted file mode 100644 index 063419633..000000000 --- a/docs/migration/index.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -id: intro -sidebar_label: Intro -title: Migrating (to TypeScript) Cheatsheet ---- - -This Cheatsheet collates advice and utilities from real case studies of teams moving significant codebases from plain JS or Flow over to TypeScript. It makes no attempt to _convince_ people to do so, but we do collect what few statistics companies offer up after their conversion experience. - -> ⚠️ This Cheatsheet is extremely new and could use all the help we can get. Solid advice, results, and up to date content all welcome. - -## Prerequisite - -Read [TypeScript's official Guide for migrating from JS](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) and you should already be familiar with their [React conversion guide](https://github.com/Microsoft/TypeScript-React-Conversion-Guide#typescript-react-conversion-guide). - -## General Conversion approaches - -- Level 0: Don't use TypeScript, use JSDoc - - See our [JSDoc section](./js-docs.md) -- Level 1A: Majority JavaScript, increasingly strict TypeScript - - as recommended by [official TS guide](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) - - use `allowJS` (Experiences: [clayallsop][clayallsop], [pleo][pleo]) -- Level 1B: Total rename to TypeScript from the start - - "[Just rename all .js files to .ts](https://twitter.com/jamonholmgren/status/1089241726303199232)"? - - use the loosest, bare minimum settings to start with -- Level 2: Strict TypeScript - - use Microsoft's [`dts-gen`](https://github.com/microsoft/DefinitelyTyped-tools/tree/main/packages/dts-gen) to generate `.d.ts` files for your untyped files. [This SO answer](https://stackoverflow.com/questions/12687779/how-do-you-produce-a-d-ts-typings-definition-file-from-an-existing-javascript) has more on the topic. - - use `declare` keyword for ambient declarations - see [declaration merging](https://github.com/typescript-cheatsheets/react#troubleshooting-handbook-bugs-in-official-typings) to patch library declarations inline - -Misc tips/approaches successful companies have taken - -- `@ts-expect-error` on compiler errors for libraries with no typedefs -- pick ESLint over TSLint (source: [ESLint](https://eslint.org/blog/2019/01/future-typescript-eslint) and [TS Roadmap](https://github.com/Microsoft/TypeScript/issues/29288)). [You can convert TSlint to ESlint with this tool](https://github.com/typescript-eslint/tslint-to-eslint-config). -- New code must always be written in TypeScript. No exceptions. For existing code: If your task requires you to change JavaScript code, you need to rewrite it. (Source: [Hootsuite][hootsuite]) - -
- - -Webpack tips - - - -- webpack loader: `awesome-typescript-loader` vs `ts-loader`? (there is some disagreement in community about this - but read [awesome's point of view](https://github.com/s-panferov/awesome-typescript-loader#differences-between-ts-loader)) -- Webpack config: - -```js -module.exports = { - -resolve: { -- extensions: ['.js', '.jsx'] -+ extensions: ['.ts', '.tsx', '.js', '.jsx'] -}, - -// Source maps support ('inline-source-map' also works) -devtool: 'source-map', - -// Add the loader for .ts files. -module: { - loaders: [{ -- test: /\.jsx?$/, -- loader: 'babel-loader', -- exclude: [/node_modules/], -+ test: /\.(t|j)sx?$/, -+ loader: ['awesome-typescript-loader?module=es6'], -+ exclude: [/node_modules/] -+ }, { -+ test: /\.js$/, -+ loader: 'source-map-loader', -+ enforce: 'pre' - }] -} -}; -``` - -Special note on `ts-loader` and 3rd party libraries: https://twitter.com/acemarke/status/1091150384184229888 - -
- -## Academic Studies of Migration - -> Note: Empirical Software Engineering is desirable, but [extremely hard](https://hillelwayne.com/talks/what-we-know-we-dont-know/). Please be gentle but also please share if you find quality research! - -- [To Type or Not to Type: Quantifying Detectable Bugs in JavaScript](http://earlbarr.com/publications/typestudy.pdf) - -> Our central finding is that both static type systems find an important percentage of public bugs: both Flow 0.30 and TypeScript 2.0 successfully detect 15%! - -- [Empirical study on the impact of static typing](https://www.researchgate.net/publication/259634489_An_empirical_study_on_the_impact_of_static_typing_on_software_maintainability) - -see also [Things I was Wrong About: Types](https://v5.chriskrycho.com/journal/things-i-was-wrong-about/1-types/) and [A Large Scale Study of Programming Languages -and Code Quality in GitHub](https://web.cs.ucdavis.edu/~filkov/papers/lang_github.pdf) - -## Misc migration stories by notable companies and open source - -- (2022) Stripe: https://stripe.com/blog/migrating-to-typescript ([podcast](https://devtools.fm/episode/33), [tweet](https://twitter.com/alunny/status/1501261144341680130)) -- [Bloomberg](https://www.techatbloomberg.com/blog/10-insights-adopting-typescript-at-scale/) - [Podcast form](https://talkscript.sitepen.com/episode-57-typescript-at-scale/) -- [Adopting TypeScript at Scale - AirBnB's conversion story and strategy](https://www.youtube.com/watch?v=P-J9Eg7hJwE) -- Airtable's [Big Bang Migration from Flow to TS](https://medium.com/airtable-eng/the-continual-evolution-of-airtables-codebase-migrating-a-million-lines-of-code-to-typescript-612c008baf5c) -- [Lyft](https://eng.lyft.com/typescript-at-lyft-64f0702346ea) -- [Google](http://neugierig.org/software/blog/2018/09/typescript-at-google.html) -- [Tiny][tiny] - [Talk from ForwardJS here](https://www.slideshare.net/tiny/porting-100k-lines-of-code-to-typescript) -- [Slack](https://slack.engineering/typescript-at-slack-a81307fa288d) ([podcast](https://softwareengineeringdaily.com/2017/08/11/typescript-at-slack-with-felix-rieseberg/)) -- [Etsy](https://codeascraft.com/2021/11/08/etsys-journey-to-typescript/) -- [Netflix adoption story](https://www.youtube.com/watch?v=p5Hwb1YbNMY&feature=share) -- [Priceline](https://medium.com/priceline-labs/trying-out-typescript-part-1-15a5267215b9) -- Dropbox - - [Talk at React Loop](https://www.youtube.com/watch?v=veXkJq0Z2Qk) - - [Blogpost: The Great CoffeeScript to TypeScript Migration of 2017](https://dropbox.tech/frontend/the-great-coffeescript-to-typescript-migration-of-2017) -- [Heap - How we failed, then succeeded, at migrating to TypeScript](https://heap.io/blog/migrating-to-typescript) -- Execute Program (Gary Bernhardt) https://www.executeprogram.com/blog/porting-to-typescript-solved-our-api-woes - -Open Source - -- [Jest's migration (PR)](https://github.com/facebook/jest/pull/7554#issuecomment-454358729) -- [Expo's migration (issue)](https://github.com/expo/expo/issues/2164) -- [Google Workbox migration](https://github.com/GoogleChrome/workbox/pull/2058) -- [Chrome Dev Tools related issues](https://twitter.com/TimvdLippe/status/1220393069792694281) -- [Atlassian's migration (PR)](https://github.com/atlassian/react-beautiful-dnd/issues/982) -- [Yarn's migration (issue)](https://github.com/yarnpkg/yarn/issues/6953) -- [React Native CLI](https://github.com/react-native-community/cli/issues/683) -- [Next.js](https://nextjs.org/blog/next-9) -- React Router - - [v5 attempt](https://github.com/ReactTraining/react-router/issues/6955) - - [React Router v6](https://github.com/ReactTraining/react-router/releases/tag/v6.0.0-alpha.4) - - [history](https://github.com/ReactTraining/history/pull/774) - [final](https://github.com/ReactTraining/history/commit/1e91a64a858604062d804e4d51eb1d2a020a95c8) -- [Docusaurus v2](https://github.com/facebook/docusaurus/pull/2578) -- [Gatsby](https://github.com/gatsbyjs/gatsby/issues/21995) -- [Redux](https://github.com/reduxjs/redux/pull/3536) -- [Theme-UI](https://github.com/system-ui/theme-ui/issues/668) -- [Hasura Console](https://github.com/hasura/graphql-engine/issues/4314) -- [Storybook](https://github.com/storybookjs/storybook/pulls?page=4&q=is%3Apr+sort%3Aupdated-desc+is%3Aclosed+typescript+label%3Atypescript) -- [Dojo 1 -> 2 migration](https://topenddevs.com/podcasts/javascript-jabber/episodes/jsj-277-dojo-2-with-dylan-schiemann-and-kitson-kelly) - -## Migration Results - -- Number of production deploys doubled for [Hootsuite][hootsuite] -- Found accidental globals for [Tiny][tiny] -- Found incorrect function calls for [Tiny][tiny] -- Found rarely used, buggy code that was untested for [Tiny][tiny] - -[clayallsop]: https://medium.com/@clayallsopp/incrementally-migrating-javascript-to-typescript-565020e49c88 "Incrementally Migrating JavaScript to TypeScript" -[pleo]: https://medium.com/pleo/migrating-a-babel-project-to-typescript-af6cd0b451f4 "Migrating a Babel project to TypeScript" -[tiny]: https://go.tiny.cloud/blog/benefits-of-gradual-strong-typing-in-javascript/ "Benefits of gradual strong typing in JavaScript" -[entria]: https://medium.com/entria/incremental-migration-to-typescript-on-a-flowtype-codebase-515f6490d92d "Incremental Migration to TypeScript on a Flowtype codebase" -[mstsreactconversionguide]: https://github.com/Microsoft/TypeScript-React-Conversion-Guide "TypeScript React Conversion Guide" -[coherentlabs]: https://hashnode.com/post/how-we-migrated-a-200k-loc-project-to-typescript-and-survived-to-tell-the-story-ciyzhikcc0001y253w00n11yb "How we migrated a 200K+ LOC project to TypeScript and survived to tell the story" -[hootsuite]: https://medium.com/hootsuite-engineering/thoughts-on-migrating-to-typescript-5e1a04288202 "Thoughts on migrating to TypeScript" diff --git a/docs/migration/js-docs.md b/docs/migration/js-docs.md deleted file mode 100644 index db35fec2d..000000000 --- a/docs/migration/js-docs.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: js_docs -title: JSDoc ---- - -- https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript -- webpack's codebase uses JSDoc with linting by TS https://twitter.com/TheLarkInn/status/984479953927327744 (some crazy hack: https://twitter.com/thelarkinn/status/996475530944823296) -- JSDoc can type check if using closure-compiler https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System - -Problems to be aware of: - -- `object` is converted to `any` for some reason. -- If you have an error in the jsdoc, you get no warning/error. TS just silently doesn't type annotate the function. -- [casting can be verbose](https://twitter.com/bahmutov/status/1089229349637754880) - -(_thanks [Gil Tayar](https://twitter.com/giltayar/status/1089228919260221441) and [Gleb Bahmutov](https://twitter.com/bahmutov/status/1089229196247908353) for sharing above commentary_) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 699ce4d59..3a6d7b0d1 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -110,10 +110,6 @@ module.exports = { label: "Advanced Guides", to: "docs/advanced", }, - { - label: "Migrating", - to: "docs/migration", - }, ], }, { diff --git a/website/sidebars.json b/website/sidebars.json index 7275eb5aa..5be10a3a9 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -58,12 +58,6 @@ "advanced/patterns_by_version", "advanced/misc_concerns", "advanced/types_react_api" - ], - "Migration": [ - "migration/intro", - "migration/js_docs", - "migration/from_js", - "migration/from_flow" ] } }