History: [v5] Undocumented breaking changes

[StringEpsilon]

While the release is correctly versioned as a new major release, some of the breaking changes are missing from the official changelog:

• history.listen() API changed. The callbacks are now called with an an object of shape Update instead of Location. This breaks react-router <=5.
• createLocation() was dropped
• locationsAreEqual() was dropped
• history.push() now has a different exception handling for iOS (page reload and loss of state)
• Options object(s) for createBrowserHistory (and the other two) changed shape:
  
  
  
  • baseName was removed, along with the basename feature itself.
  
  
  • forceRefresh was removed. A replacment mechanism for force refreshes has not been added to 5.0.0
  
  
  • keyLength was removed - key length in location objects is now a fixed length.
  
  
  • getUserConfirmation was removed - entire feature removed (see new blocking system)
  
  
  • window was added.
  
  
• hashType configuration for HashHistory was dropped
• createPath() no longer ensures the hash and search portions are properly prefixed before concatination.
• history.location is now frozen
• parsePath changed the handling of falsey values. v5 now returns just an empty object.
• key on the default location changed from being not defined to being defined and having the value "default".
• As part of path resolution, push("#hash") will no longer clear the search part of the location. This is the default browser behavior, but could still be seen as a breaking change.
  
  
  
  • Path resolution also deviates in other ways from v4 that are not default browser behavior, see #808 and #814 ( #859 )
  
  
• history.goBack() was renamed to history.back()
• history.forward() was renamed to history.forward()
• For typescript users: The type definitions in history@5 are not compatible with the type definitions in @types/history. If you depend on the latter, installing history@5 will result in a build failure (see #846, #835)

And the changes of the blocking features are mentioned, but not under "breaking" and not in detail:

• history.block() API changes:
  
  
  
  • The "prompt" parameter was dropped.
  
  
  • The "unblock" callback no longer accepts a parameter.
    
    (Note to reader: The blocking behavior changed beyond just the simple API changes)
  
  

Not breaking, but also not documented:

• The length of the key attribute on locations was increased from 6 to 8.
• key now works with createHashHistory as well.

(See also: #810, #809, #803, #813, and #829 )

Addendum: I'm not sure I found all the breaking changes. But appending the changelog by my findings could help people who use history directly to make an upgrade decision and find code they need to change on their end regardless.

Addendum 2: I scribbled together slightly more coherent notes on all the breaking changes. It's still incomplete and very basic, but it might help. Please comment on the gist if I got anything wrong or if you have suggestions.

[Hypnosphi]

history.location object is now frozen

[Hypnosphi]

parsePath can be used as a replacement for createLocation

[StringEpsilon]

parsePath can be used as a replacement for createLocation

I don't really see that. createLocation was quite the powerful function for calculating route changes. parsePath just splits the string according to spec.

But your comment just made me notice that parsePath changed behavior between versions too.

[StringEpsilon]

I just noticed that some of these breaking changes are also points on the roadmap (#689). @mjackson You might want to update that one as well.

[evenfrost]

createHashHistory result now has incompatible types when used as custom history provider for preact-router.

[Hypnosphi]

https://github.com/ReactTraining/history/issues/814

[shakhbulatgaz]

So what, are you guys just gonna leave this issue here, without addressing the fact that you shipped a ton of breaking changes without telling us? At least comment on it and tell us how to fix our projects now.

[mkarajohn]

So what, are you guys just gonna leave this issue here, without addressing the fact that you shipped a ton of breaking changes without telling us? At least comment on it and tell us how to fix our projects now.

I am sure they have seen the thread, but, I agree, an acknowledgement would be nice. However, don't go around demanding stuff. If this upgrade breaks your project report what's breaking, subscribe to this thread for updates, and in the meantime revert to v4. That's how it works.

[shakhbulatgaz]

@mkarajohn maybe you are right, perhaps I'm being too demanding. But just because maintainers are doing their job voluntarily does not mean they can't be held accountable for ignoring such an important issue for, what, two and a half months now?

Especially when it comes to such a fundamental and widely used library as history.

[mkarajohn]

@shakhbulatgaz I understand your frustration, v5 is unusable for me too, as it currently stands, however it's not the end of the world. I am just staying on v4 a while longer