|
| 1 | +# ADR #005: TypeScript Working Group |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +Proposed |
| 6 | + |
| 7 | +## Submitters |
| 8 | + |
| 9 | +- @bjohansebas |
| 10 | + |
| 11 | +## Decision Owners |
| 12 | + |
| 13 | +- @expressjs/express-tc |
| 14 | + |
| 15 | +## Context |
| 16 | + |
| 17 | +TypeScript is now widely adopted and has a large, active community. Many developers use it alongside packages maintained by the Express project. As such, there's a growing need to enhance TypeScript support — both by maintaining accurate type definitions and by addressing existing and future issues related to typings. |
| 18 | + |
| 19 | +- **Why do we need this decision?** |
| 20 | + |
| 21 | +As the Express project continues to evolve, we want to improve our engagement with the community. Having a dedicated group focused on TypeScript-related matters will enhance our support, especially since not all maintainers are familiar with TypeScript. An active working group will help manage and resolve type-related issues effectively. |
| 22 | + |
| 23 | +- **What problem does it solve or avoid?** |
| 24 | + |
| 25 | +This proposal aims to establish a dedicated team responsible for maintaining TypeScript types, whether in DefinitelyTyped or directly within the repositories. It will also help triage and resolve the numerous issues reported daily related to type definitions. |
| 26 | + |
| 27 | +- **Are there any existing issues/discussions/pull requests related to this?**: |
| 28 | + |
| 29 | + - https://github.com/expressjs/discussions/issues/192 |
| 30 | + - https://github.com/expressjs/express/issues/2818 |
| 31 | + |
| 32 | +## Decision |
| 33 | + |
| 34 | +Similar to the Security WG and Performance WG, we will set up a new repository (expressjs/typescript-wg) along with a corresponding action plan. This working group will be empowered to build consensus and make decisions within its scope. Its core responsibilities will include: |
| 35 | + |
| 36 | +- Ensure `express` package types are semantically correct, current with the implementation, and provide a high-quality developer experience |
| 37 | +- Making decisions on TypeScript support within Express-maintained repositories |
| 38 | +- Maintaining up-to-date TypeScript type definitions |
| 39 | +- Enhancing documentation for TypeScript usage across Express packages |
| 40 | +- Support testing type accuracy while in development and CI |
| 41 | +- Ensure that types shared across Express Project packages are updated in sync to prevent build errors across the ecosystem |
| 42 | + |
| 43 | +### Initial Goal |
| 44 | + |
| 45 | +The TypeScript Working Group’s initial goal is to ensure that the `express` package has **high-quality, semantically correct, and up-to-date type definitions that accurately reflect its public API.** |
| 46 | + |
| 47 | +As part of this effort, the working group will also evaluate whether and how to support types in other Express-maintained packages. Decisions around publishing first party types vs. DefinitelyTyped maintenance, release cycle alignment, and tooling support will be developed collaboratively and documented as part of the group's ongoing charter. |
| 48 | +We will need to take a few actions to get this started: |
| 49 | + |
| 50 | +1. Create a new `typescript-wg` repo |
| 51 | +2. Create teams: `@expressjs/typescript-wg`, `@pillarjs/typescript-wg`, `@jshttp/typescript-wg` |
| 52 | +3. Write charter/goals doc in the new repo |
| 53 | + |
| 54 | +## Rationale |
| 55 | + |
| 56 | +Since Express has become active again and the new version, Express v5, has been released, several issues related to typings have emerged. There have also been discussions about actively integrating type definitions within the repositories. |
| 57 | + |
| 58 | +Most packages under the Express umbrella are not written in TypeScript, and not all maintainers are interested in taking on type maintenance responsibilities. A small number (such as `path-to-regexp`) maintain their own types, but this is the exception rather than the norm. |
| 59 | + |
| 60 | +The proposed working group provides a focused avenue for contributors who are interested in TypeScript to collaboratively improve, maintain, and guide the strategy for type definitions across Express projects, starting with the core `express` package. |
| 61 | + |
| 62 | +## References |
| 63 | + |
| 64 | +- https://github.com/expressjs/discussions/issues/192 |
| 65 | +- https://github.com/expressjs/express/issues/2818 |
| 66 | + |
| 67 | +## Changelog |
| 68 | + |
| 69 | +Track changes or updates to this ADR over time. Include the date, author, and a brief description of each change. |
| 70 | + |
| 71 | +- **[2025-05-28]**: [@bjohansebas] - Initial draft |
| 72 | + |
0 commit comments