React-router: Packaged Typescript Definitions

[tills13]

Basically all that would be required in v3 is copying the definitions from here into the project. Going forward, it would mean that new releases of React Router (especially those with breaking changes to the API, such as with v4) would immediately have access to TypeScript typings instead of relying on the community to scramble to update the definitions.

Refer to this document for more information on publishing NPM packages with built-in TypeScript types.

[timdorr]

I'm against this because of the version management. TS and Router have two different release cycles, so we might end up getting ahead or behind whatever the major version of TS is. If 3.0 just came out and we published a patch version of Router that used TS 3.0-only features, that would actually bump the version of the Router up to a major. It becomes kind of a mess really easily.

Also, no one on the maintainer list is a TS expert (AFAIK). So, we would have to rely on the community to help maintain them. And if that's the case, it's best left on DefinitivelyTyped as an external addon. The tooling handles this with the @types npm namespace pretty well as-is.

[mjackson]

Agree w @timdorr. Unfortunately nobody who maintains react-router uses TS, so we'd always have to rely on someone to come in and update them for us. This is something that is better left to people who really care about TS.

[tills13]

@timdorr just to clarify, I'm only talking about including the _definitions_ in the RR project, not porting the whole project over to TS - it's a little hard to tell which you're talking about.

In any case, thanks for the response.

[GeKorm]

To add to the above comment, type definitions help with code completion, type checking and other IDE hints. This is a proposal for ReactTraining to maintain the definitions instead of the community (package linked above).

[tills13]

To add further to what @GeKorm wrote, the TS definitions also help with vanilla JavaScript type hinting/"intellisense" in editors like VSCode.

I genuinely think that this is an issue worth investing time into.

[timdorr]

@tills13 Yep, that's what I'm talking about too. We're on the same page.

The core thing is this has to be community maintained regardless. We don't know how to best build typedefs ourselves. Whether we set up a react-router-types subpackage or it lives on DT, we're not going to be the ones writing that code. And given its proliferation and ability to progress relative to TS, not Router's release schedule, DT would seem to be the best way to maintain those typings.

[donaldpipowitch]

Sorry for this cross post from https://github.com/ReactTraining/history/pull/377#issuecomment-288392859. I think having type declarations would help the documentation. IMHO currently it is a little bit ambiguous, if some prop can be undefined or not.

[Izhaki]

Why separate the tightly coupled?

Whilst DT exists, a lot of pain would be spared if each library shipped with its own typings attached. See 'Including declarations in your npm package' in https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

The problem with having @types/react-router is that the two projects has to be kept in sync, and there is no authority to approach when it comes to typings issue.

Getting hang of typings isn't quite rocket science, and most of it, if not all, can be automatically generated using tsc. Or, you can just copy what's on DT, and ping the OP when issues pop up here.

[dustinws]

Hello everyone, just bumping this thread, even though it is closed. Second time is a charm?

@timdorr I could be wrong, but I believe you can include the definition files without actually placing a dependency on typescript. Just having the index.d.ts on the top level of your package is enough for consumers reap the benefits. With this in mind, I'm a little confused about why you think the release schedule could cause trouble. This thread isn't about converting code to TS or adding dependencies, it's simply adding one file to the project, no more. It's affect on the library is exactly the same as adding additional documentation.

If 3.0 just came out and we published a patch version of Router that used TS 3.0-only features, that would actually bump the version of the Router up to a major.

Is this really the case? In definition files, you're not providing any implementations. No part of the react-router package needs to be in typescript. We're simply adding definitions to reflect the state of the javascript api. Unless typescript completely deprecates it's type system for something new, I don't think we have any worries in this department.

I understand the argument that no one on the core team is a personal user of TS, and therefore the typings are best left to the community because it probably means someone with a higher understanding of TS will write the files for you, which is beneficial for everyone.

With that said, downloading the typings separately from another package is the common route these days, but is that correct? This is only the case because of all of the existing libraries when typescript was released, but we're seeing more and more projects written in TS, and even seeing definition files exported by projects written in JS, for the consumer's convenience.

Personally, I feel that even more projects will pick this up, and it's only making our lives as developers easier.

Would you and the other core members consider another contributor who is a bit more TS savvy? This person could help with regular issues, but also be responsible for keeping the definitions in sync.

This would add the benefit of

• _official_ typings exported from the library (who doesn't love branding?)
• typings that are reliably in sync with the api (less of these types of issues)
• JS and TS users can reap the benefits. Using an editor like vscode or something else with the ternjs system will pick up these types and allow for Intellisense on regular JS files.

I really do think that this could be beneficial for both Typescript users and regular Javascript users alike.

Any thoughts from the team?