Proposal to Adopt TypeScript in Video.js

[hichemfantar]

Introduction

Video.js has been a widely used open-source project that provides a reliable and extensible HTML5 video player for the web. As the ecosystem around JavaScript continues to grow, the need for more robust tools that enhance code quality, scalability, and developer productivity becomes critical. TypeScript, a superset of JavaScript, offers static typing and advanced tooling that can significantly improve the Video.js codebase.

This proposal outlines the benefits, potential challenges, and steps required to adopt TypeScript in Video.js.

Benefits of Adopting TypeScript

1. Improved Code Quality and Maintenance:

   • TypeScript’s static typing helps catch errors during development, which reduces runtime errors. This can improve the overall quality and reliability of the Video.js codebase.
   • Clear type definitions make the code easier to understand and maintain, especially in large-scale projects like Video.js, which can be extended with plugins and external contributions.

2. Enhanced Developer Experience:

   • TypeScript provides better autocompletion, navigation, and refactoring tools in modern IDEs. This reduces the time developers spend on debugging and code exploration, improving their overall productivity.
   • New contributors, particularly those familiar with TypeScript, will have an easier onboarding process due to enhanced clarity in code structure and expected types.

3. Scalability:

   • As the Video.js ecosystem grows, including the addition of more plugins and complex integrations, TypeScript’s type system will make it easier to scale the project. Clear contracts between components and libraries can help avoid integration issues.

4. Better Ecosystem Integration:

   • Many modern libraries, tools, and frameworks (React, Angular, etc.) are TypeScript-first. Moving Video.js to TypeScript will make it easier to integrate with other tools, enhancing the extensibility of the player for users and developers alike.

5. Future-Proofing:

   • TypeScript adoption is on the rise, with a strong backing from Microsoft and a growing community. Converting to TypeScript positions Video.js to stay competitive.

Potential Challenges

1. Initial Migration Effort:

   • Converting a large project like Video.js to TypeScript may require significant effort in rewriting and ensuring type correctness across the codebase. This can be mitigated by adopting TypeScript incrementally, focusing on core modules first.

2. Contributor Adaptation:

   • Current contributors familiar with JavaScript but not TypeScript may face a learning curve. To ease this transition, comprehensive documentation and resources on TypeScript can be provided.

3. Plugin Ecosystem:

   • Since Video.js has an extensive plugin ecosystem, maintaining backward compatibility for plugins written in JavaScript will be essential. TypeScript allows gradual adoption, meaning plugins can continue to work without immediate migration.

4. Build Configuration Complexity:

   • Adopting TypeScript will introduce new tooling and build configurations (e.g., tsconfig.json, type declarations). However, modern build systems like Webpack and Rollup have good TypeScript support, and tools like Babel can help ease the transition.

Plan for Migration

The migration can be carried out incrementally to ensure minimal disruption to the existing codebase and the ecosystem.

1. Phase 1: Tooling Setup (this seems to be done already)

   • Set up the basic TypeScript configuration (tsconfig.json) in the Video.js project.
   • Integrate TypeScript into the build pipeline using Babel or Webpack to ensure seamless compilation alongside existing JavaScript.

2. Phase 2: Incremental Migration

   • Begin by converting non-critical modules and utility functions to TypeScript. This will provide the team with hands-on experience while maintaining the core functionality.
   • Start defining interfaces and types for core components. For instance, type definitions for player configuration options, event handling, and media playback should be a priority.
   • Work on defining type definitions for public APIs while ensuring backward compatibility.

3. Phase 3: Full Module Conversion

   • Gradually convert major components like the player, control bar, and media handling modules to TypeScript.
   • Ensure tests are refactored as needed to handle TypeScript changes, using Jest or other suitable testing frameworks with TypeScript support.

4. Phase 4: Ecosystem and Plugin Support

   • Provide clear guidelines for plugin authors on how to migrate their plugins to TypeScript if they wish. Offer type definitions for the plugin API.
   • Maintain backward compatibility by ensuring that the core player can load JavaScript plugins seamlessly.

5. Phase 5: Final Cleanup and Documentation

   • Once the core components and plugins have been converted, focus on polishing the codebase by adding any missing type definitions, refining build processes, and improving test coverage.
   • Update the official documentation with guidelines for contributing to Video.js using TypeScript.

Conclusion

Adopting TypeScript in Video.js will improve the maintainability, scalability, and reliability of the project. It will enhance developer productivity and contribute to the long-term health of the project by positioning it as a modern, forward-looking library. With a phased approach to migration, the transition can be handled smoothly, minimizing disruption while ensuring the community continues to benefit from the flexibility and extensibility of Video.js.

I believe that this move will help Video.js continue to be a top choice for developers building video experiences on the web.

---

Let me know if you would like to refine or add any specific details to this proposal!

[welcome[bot]]

👋 Thanks for opening your first issue here! 👋

If you're reporting a 🐞 bug, please make sure you include steps to reproduce it. We get a lot of issues on this repo, so please be patient and we will get back to you as soon as we can. To help make it easier for us to investigate your issue, please follow the contributing guidelines.

[misteroneill]

Hello @hichemfantar!

Brightcove and the Video.js collaborators are planning on doing just this!

We have struggled for years now to make a 14 year old plain JavaScript project with JSDoc comments play nicely with TypeScript... with very mixed results (obviously).

At a high level, it starts with a project we call VHS Next. This will rewrite our playback engine, VHS, in TypeScript. Following that, we will do the same with Video.js itself - along with some significant architectural changes as well. There will be an RFC for that, of course, as well, sometime in 2025.

Please feel free to engage with the RFC(s) as they come up and your collaboration would be welcome!

[hichemfantar]

@misteroneill Thanks for letting me know about the project! It seems VHS Next is still very far in the future and I'm thinking something more short term. Wouldn't converting the existing codebase to TS make the transition to the new architecture much smoother and less error prone due to the advantages of TS?