• Status: Proposed
• Deciders: Michael White / Chris McCue / Tony Braasch / Willem Paul / Sharan Kandagatla / Scott Houser / Thomas Musengwa / Bailey Surowiec / Neil Patel / Alex Chen / Marcus Taugner / Dylan Surprise / Richard Plotkin
• Date: 12/7/2023
• Last Updated: 2/8/2024

Context

The Abyss framework, currently written in JavaScript, is at a crossroads regarding the adoption of TypeScript. Considering the evolving needs of the product teams consuming Abyss components and the current resource allocation, we faced a decision between adding type declaration files to our existing JavaScript codebase and converting the entire codebase to TypeScript.

Decision

We have decided to add type declaration files to the Abyss components while keeping the majority of the existing codebase in JavaScript. This approach is intended to provide immediate benefits to consuming teams without the extensive overhead of a full codebase conversion that would delay the delivery of these much needed declarations.

Update on 2/6/2024

After further team discussions and evaluation, we are updating our approach to adopt TypeScript in two steps:

1. Release Manual Type Declarations: Start with web components, as most have type declarations ready for consumption. We will batch components in small PR bundles for team review. A working branch named refactor/web-type-declarations will be the staging area until we are ready to merge into the main branch and release.
2. Incremental Codebase Conversion: Begin gradual conversion of the existing JavaScript codebase to TypeScript, prioritizing components where TypeScript can add the most value. Planning and resources will be allocated to ensure a smooth transition.

• Plan for Mobile Components: Mobile components have partial type declarations available. A timeline for completion and testing will be established to enable release of these declarations and eventual conversion of existing codebase to TypeScript.

Consequences

• Original Pros:

  • Quicker implementation, allowing for faster delivery to consuming product teams. (Clarifying that this is stating it would be a quicker implementation to release manual type declarations than converting the entire codebase before making these type declarations available to the consuming teams.)
  • Immediate value addition to teams using Abyss components, providing them with necessary type declarations that they've been requesting for some time. (Clarifying that the speed of providing these types to consuming teams was covered in the prior bullet and makes this point irrelevant.)
  • More control over specific functionalities we want to define and expose within the type declarations. (Upon further review and exploration, this was found to be less of a benefit than originally anticipated.)

• Original Cons:

  • The underlying JavaScript codebase will remain without TypeScript's strict typing benefits.
  • Potential concerns of increased development time from Abyss Admiral contributions regarding the non-type safety of the existing code.

• Updated Pros:

  • Immediate provision of type declarations to product teams with manual typings for consumption.
  • A significant portion of the web component library already has manual typings tested and ready for release.

• Updated Cons:

  • Gradual conversion may lead to temporary inconsistencies in the codebase during the transition period.

Alternatives Considered

Full Conversion to TypeScript: Initially, converting the entire Abyss codebase to TypeScript was considered as a viable alternative.

• Original Pros:

  • Consistency with other TypeScript applications, potentially adding value to the Abyss Admiral program.
  • Automatic generation of type declarations.

• Original Cons:

  • Significant time and resource investment required for conversion. (Clarifying that this is primarily true as it relates to our more complex components, such as DataTable. This is primarily due to the fact these components include layers of sub-components and custom hooks that will need to be converted, versus the manually created type declarations which only need to address components, hooks and tools that are accessible by the user.)
  • Increased workload amidst the demands of onboarding new teams in 2024, impacting our capacity for existing code refactoring. (Acknowledging we should always make the best technical decision possible, and then determine how to work with it.)
  • Potential knowledge gap for developers more familiar with JavaScript than TypeScript. (Acknowledging that for less seasoned developers the addition of type checks could be a pro and help reduce errors.)
  • New study reports that Typescript uses more than 5x the resources of energy and time than Javascript
  • There is a trend developing of large open-source frameworks such as Svelte, ditching Typescript, to reduce the size of the packages.

Update on 2/6/2024

After further discussions and evaluations, we have reaffirmed the value of a consistent, type-safe codebase offered by TypeScript. Consequently, we are adopting an incremental approach to the TypeScript conversion of the Abyss codebase. This strategy enables us to transition smoothly without disrupting ongoing projects, aligns with our immediate priorities, and allows for continued delivery of value to our stakeholders.

Future Considerations

• Monitor and Evaluate: Continuously assess the impact of this decision on both the developer experience and the efficiency of consuming teams.
• Potential Incremental Adoption: Consider gradually introducing TypeScript into parts of the codebase where it might bring the most benefit.
• Develop New Components in TypeScript: Develop new components in TypeScript to ease future integration and improve type safety.

Revision History

• 12/7/2023: Initial decision to implement manual type declarations instead of full conversion.section.
• 2/6/2024: Updated the decision to initially release manual type declarations, followed by a phased, incremental conversion of the codebase to TypeScript.
• 2/8/2024: Added full list of deciders.