[Epic] TypeScript refactor

[colebemis]

Objective

Rewrite Primer React components in TypeScript.

📄 TypeScript ADR
📄 TypeScript notes google doc

Team

• DRI: @colebemis
• Engineering: @colebemis @smockle @bscofield @VanAnderson
• Product: n/a
• Design: n/a

Tasks

Phase 1: Setup

• Support .ts and .tsx files TypeScript refactor #959
• Type check test files Type check test files #971

Phase 2: Migrate

• Migrate components¹

In Review or Done

• Dialog @VanAnderson Migrate Dialog component to TypeScript #1060
• Dropdown @colebemis Migrate Dropdown to TypeScript #1059
• theme @colebemis Migrate theme to TypeScript #1058
• utils @VanAnderson Migrate utils to TypeScript #1055
• SelectMenu @colebemis Migrate SelectMenu to TypeScript #1048
• Pagination @VanAnderson Migrate Pagination to TypeScript #1047
• PointerBox @colebemis Migrate PointerBox to TypeScript #1042
• SideNav @VanAnderson Migrate SideNav to TypeScript #1040
• SubNav @VanAnderson Migrate SubNav component to TSX #1038
• Timeline @colebemis Migrate Timeline to TypeScript #1037
• CircleOcticon @colebemis Migrate CircleOcticon to TypeScript #1036
• CircleBadge @colebemis Migrate CircleBadge to TypeScript #1035
• Popover @colebemis Migrate Popover to TypeScript #1034
• Tooltip @colebemis Migrate Tooltip to TypeScript #1033
• AvatarStack @colebemis Migrate AvatarStack to TypeScript #1032
• TabNav @VanAnderson Migrate TabNav component to TSX #1029
• AvatarPair @colebemis Migrate AvatarPair to TypeScript #1031
• Caret @colebemis Migrate Caret to TypeScript #1030
• TextInput @colebemis Migrate TextInput to TypeScript #1028
• Details @VanAnderson Migrate Details component to TSX #1026
• Button @smockle feat: Migrate button components to TypeScript #1017
• Header @VanAnderson Migrate Header component to TSX #1020
• FilterList @colebemis Migrate FilterList to TypeScript #1015
• UnderlineNav @colebemis Migrate UnderlineNav to TypeScript #1014
• Breadcrumb @colebemis Migrate Breadcrumb to TypeScript #1012
• Link @VanAnderson convert link component to typescript #1011
• StateLabel @colebemis Migrate StateLabel to TypeScript #1008
• FilteredSearch @colebemis Migrate FilteredSearch to TypeScript #1006
• CounterLabel @colebemis Migrate CounterLabel to TypeScript #1005
• Truncate @colebemis Migrate Truncate to TypeScript #1003
• FormGroup @colebemis Migrate FormGroup to TypeScript #999
• Position @colebemis Migrate Position to TypeScript #998
• Flash @colebemis Migrate Flash to TypeScript #995
• StyledOcticon @colebemis Migrate StyledOcticon to TypeScript #993
• ProgressBar @colebemis Migrate ProgressBar to TypeScript #987
• Avatar @bscofield Migrate Avatar to TypeScript #984
• Grid @colebemis Migrate Grid to TypeScript #989
• Flex @colebemis Migrate Flex to TypeScript #986
• BorderBox Migrate BorderBox to TypeScript #973
• Text Migrate Text to TypeScript #979
• BaseStyles Migrate BaseStyles to TypeScript #982
• Box TypeScript refactor #959
• BranchName Migrate BranchName to TypeScript #974
• Heading Migrate Heading to TypeScript #975
• Label Migrate Label to TypeScript #976
• LabelGroup Migrate Label to TypeScript #976
• Pagehead Migrate Pagehead to TypeScript #977

Phase 3: Clean up

• Remove ambient declaration file (index.d.ts) Replace index.d.ts with generated type definitions #1147
• Remove propTypes Remove propTypes #1068

Postponed

• Update contributor guidelines
• Remove default exports
• Generate prop documentation Generate prop documentation #1109

¹How to migrate a component to TypeScript

The migration process for each component may vary, but it will likely follow these high-level steps:

1. Change the file extension from .js to .tsx

src/Box.js → src/Box.tsx

2. Add type annotations to the component file

Here are type annotations for the Box component:

  // src/Box.tsx
  import styled from 'styled-components'
+ import {COMMON, FLEX, LAYOUT, SystemCommonProps, SystemFlexProps, LayoutProps} from './constants'
+ import sx, {SxProp} from './sx'
+ import {ComponentProps} from './utils/types'


+ const Box = styled.div<CommonProps & FlexProps & LayoutProps & SxProp>`
    ${COMMON}
    ${FLEX}
    ${LAYOUT}
    ${sx}
  `
+ export type BoxProps = ComponentProps<typeof Box>
  export default Box

Most Primer React components will follow a similar pattern. Each component should export a ___Props type in addition to the default export.

3. Change the file extension of tests

src/__tests__/Box.js → src/__tests__/Box.tsx

👉 See the TypeScript notes google doc for more information on TypeScript migration.

Exit criteria

• All JavaScript files in the src directory of primer/components have been rewritten in TypeScript

/cc @philipbremer

[colebemis]

Status

💚 Green

Ships

We removed propTypes from all our components in favor of TypeScript types.

Blockers

We’re getting as prop-related errors when testing the generated type definitions in Memex which is blocking us from merging #1067

Up Next

• I'll be meeting with @T-Hugs next week to discuss the as prop errors and brainstorm possible workarounds.
• I'll be adding TypeScript guidelines to the contribution guidelines

[colebemis]

Status

💛 Yellow

Blockers

The final step of this TypeScript refactor is to replace our manually maintained type definitions with type definitions generated by TypeScript. However, after testing in Memex, I found that the generated type definitions were causing errors because of the way the as prop is defined.

I figured out a way to correctly define types for the as prop but it will require us to update all our components:

Here's an example of how our components will need to be updated

import styled from 'styled-components'
import {COMMON, FLEX, LAYOUT, SystemCommonProps, SystemFlexProps, SystemLayoutProps} from './constants'
import sx, {SxProp} from './sx'
- import {ComponentProps} from './utils/types'
+ import {ForwardRefComponent} from './utils/polymorphic'

+ const defaultElement = 'div'

+ export type BoxProps = SystemCommonProps &
+  SystemFlexProps &
+  SystemLayoutProps &
+  SxProp

+ type BoxComponent = ForwardRefComponent<typeof defaultElement, BoxProps>

+ const Box = styled(defaultElement)<BoxProps>`
- const Box = styled.div<BoxProps>`
  ${COMMON}
  ${FLEX}
  ${LAYOUT}
  ${sx};
+ ` as BoxComponent
- `

- export type BoxProps = ComponentProps<typeof Box>
export default Box

I haven't had time to completely implement this solution because of Primer React theming work. I'll reach out to @VanAnderson to see if he as the bandwidth to take this on.

Up Next

• Fix the as prop types so we can replace our manually maintained type definitions with type definitions generated by TypeScript
• Add TypeScript guidelines to the contribution guidelines

[colebemis]

Status

💛 Yellow

No updates on TypeScript this week because @VanAnderson and I have been focused on the Primer React theming epic.

Up Next

• Fix the as prop types so we can replace our manually maintained type definitions with type definitions generated by TypeScript
• Add TypeScript guidelines to the contribution guidelines

[colebemis]

Status

💛 Yellow

No updates on TypeScript this week because @VanAnderson and I have been focused on the Primer React theming epic. I'll have the bandwidth to finish up TypeScript work next week.

Up Next

• Fix the as prop types so we can replace our manually maintained type definitions with type definitions generated by TypeScript
• Add TypeScript guidelines to the contribution guidelines

[colebemis]

4/1 Update

Status 💚

Ships

This week we replaced our hand-written type definitions with type definitions generated by the TypeScript compiler (#1147). This means consumers get more accurate type definitions and maintainers no longer have to manually keep the type definitions in sync with the code! This is the culmination of a quarter-long effort to rewrite Primer React in TypeScript 🎉 (#970). These changes will be included in the next release of Primer React.

Up Next

• Write guidelines for authoring components in TypeScript.

[colebemis]

The exit criteria has been met 🎉 I'm going to go ahead and close this issue. We can track follow-up tasks in separate issues.