Aspnetcore: Clearly Describe which SignalR npm Package to Use

[simonua]

Is your feature request related to a problem? Please describe.

I was trying to determine the difference between @aspnet/signalr and @microsoft/signalr to use in my JavaScript / Angular application.

My challenges:

• It was not clear to me which package to use. @aspnet/signalr has a higher weekly download but fairly stagnant download growth whereas @microsoft/signalr has a smaller weekly download but growing adoption.
• Both packages have an almost identical README in the package as seen on npm.
• Microsoft's documentation did not clearly call out which one to use.

I decided to pursue @microsoft/signalr as it was updated 15 days ago whereas @aspnet/signalr was updated a year ago.

My next steps in researching this path further:

1. Starting on @microsoft/signalr, I clicked on SignalR Documentation.
2. I clicked on Supported Platforms in the menu tree.
3. I then clicked on the JavaScript Client header.

Informative, but a bit of a dead-end here as I still didn't know what version to use.

I then tried this:

1. Starting on @microsoft/signalr again, I clicked on Homepage (property in package.json) on the right.
2. In the _Packages_ section, this was revealed:

Describe the solution you'd like

It would be helpful to point out which package to use more clearly on npm and more visibly in the Microsoft documentation.

[gfoidl]

Microsoft's documentation did not clearly call out which one to use.

Really?
For ASP.NET Core have a look at https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-3.1#install-the-signalr-client-package

[simonua]

You might have taken a different path than me to get to that. If you look at my steps and my screenshot, maybe it's understandable why it was confusing. This could just be called out a bit more explicitly, in my opinion.

[BrennanConroy]

We can consider deprecating the @aspnet/signalr client with a message about the new client. New clients still work with older server versions, so there should be no breaks when people switch to a new client.

@anurse we talked about this before. Do you remember why we didn't deprecate earlier?

[bradygaster]

@simonua thanks for your detailed synopsis of how you got a bit confused here, and our apologies for it. As @gfoidl pointed out, that is our main doc on the latest version of the JavaScript client, which is absolutely the @microsoft/signalr package. I'll retrace your steps and do what I can to make that journey less confusing for folks.

[anurse]

Do you remember why we didn't deprecate earlier?

@aspnet/signalr version 1.0.x (which maps to .NET Core 2.1) is still LTS supported, so it's not really appropriate to deprecate a fully supported package.

What we can (and should do) though is update the README for the package. That seems like a reasonable way to clear up some confusion. Something like:

**NOTE: Starting with version 3.0, this package has moved to `@microsoft/signalr`**

Informative, but a bit of a dead-end here as I still didn't know what version to use.

@simonua can you clarify what was confusing here? The doc you ended up on is pretty clear as to which package to install, and npm will install the latest (which is the appropriate behavior).

In general, SignalR clients are designed to be fully backwards and forwards compatible. In relation to this (and other similar questions) I've opened https://github.com/dotnet/AspNetCore.Docs/pull/18293 to update our docs.

[simonua]

Thanks, everyone, for the conversation.

Hi @anurse, there's a difference in perspective here, I think, in that I looked at it from an npm perspective where I had two choices that didn't differ based on information on the registry whereas you looked at it from a much clearer Microsoft docs perspective. I think the latter is fine, and you are right that the doc is clear. What I wish for would be less ambiguity from a registry perspective, so that I could immediately see that one package is just on LTS now but no longer the preference. I fully agree with you with respect to updating the README for the @aspnet/signalr package. That would be appreciated. Thank you!

[BrennanConroy]

Action item:

What we can (and should do) though is update the README for the package. That seems like a reasonable way to clear up some confusion. Something like:

**NOTE: Starting with version 3.0, this package has moved to `@microsoft/signalr`**

This would need to go into the 2.1 branch and be brought to tactics.

We also might want to mark the latest tag on npm with the 1.0.x version as that's the LTS version and the 1.1.X package is end-of-life.

[bradygaster]

adding @Pilchie to the discussion per the tactics mention.

[Pilchie]

I think we're ready to merge the associated PRs for July servicing, right?

[BrennanConroy]

Done with https://github.com/dotnet/aspnetcore/pull/22129