[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.

The following is an incomplete list of breaking changes. Some changes listed in the official changelogs are not mentioned here.
So please consult the official changelogs as well:

Open for list of links

• 5.0.0
• 5.1.0
• 5.2.0
• 5.3.0

Be aware that some of the changes are also mentioned in the beta changelogs but not repeated in the official 5.0.0 release notes:

• 5.0.0-beta.0
• 5.0.0-beta.1
• 5.0.0-beta.2
• 5.0.0-beta.3
• 5.0.0-beta.4
• 5.0.0-beta.5
• 5.0.0-beta.8

Removed APIs

• createLocation() was dropped
• locationsAreEqual() was dropped
• history.length was dropped #960
• The hashType configuration for HashHistory was dropped (see #912 and #953)
• Support for basename was dropped. #810

Renamed attributes and functions

• history.goBack() was renamed to history.back() #829
• history.goForward() was renamed to history.forward()

Changed APIs

history.listen

The history.listen() API changed. The callbacks are now called with an an object of shape Update instead of Location.
This breaks react-router <=5.

Before, the callbacks where called as callback(location, action).
Now they are called with invoked like this: callback({action, location}).
v5 docs
v4 docs

Related issue: #803

TypeScript

The type definitions in history@5 are completely incompatible 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).

options

The options for createBrowserHistory, createHashHistory and createMemoryHistory all 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.

pasePath

parsePath() changed the handling of falsey values. v4 used to return a default location of {pathname: "/", search: "", hash: ""}, v5 returns {}

history.location

history.location is now frozen

Blocking

Blocking Transitions

The entire blocking system has been redesigned from scratch and is therefore completely incompatible. Please refer to the v5 documentation for how the new system works:

History v5 Documentation

For comparison, here is the v4 documentation.

Immediately, two changes jump out in particular in terms of API surface. Though the behavior also changed:

• history.block() no longer accepts a prompt parameter.
• The 'unblock' callback no longer accepts a parameter

#830
#921
#933

Miscellanious other changes:

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

Changes in behavior

encoding / decoding

Pathnames are no longer encoded / decoded the same way.
See #551 and #516 for the background.
Also see #884

history.push exception handling

history.push() now has a different exception handling for iOS (page reload and loss of state). Basically, the library now forces the location via window.location.assign(url); now, where it did not catch the exception before. Relevant code
This new handling can also allow for XSS in some cases. See #850

createPath

createPath() no longer ensures the hash and search portions are properly prefixed before concatination.

See issue #813.
This was fixed in pull request 891.

Affected versions are 5.0.0 and 5.1.0. Was fixed in 5.2.0

location.key

The key on the default location changed from being not defined to being defined and having the value "default".

Before:

if (!history.location.key) {
	handleDefaultLocation();
}

After:

if (!history.location.key === "default) {
	handleDefaultLocation();
}

path resolution

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 issues #808, #814 and #859

---

Addendum 1: 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: [obsolete]

---

Addendum 3: Michael commented on the intention behind (some of) the breaking changes and history as a library going forward here: #810 (comment) Quote:

The goal with history v5 is to make this library just an implementation detail of React Router v6. Nowhere in the RR v6 API do you get a handle on the history object. It's completely hidden.
[...]
Anyway, like I said I know this is going to require some work but I just wanted y'all to know that we are doing it for a reason and hopefully adapting to this kind of architecture will better prepare you for the future.

---

Last Addendum: I have added a couple more breaking changes that issues popped up for since my last update ~1.5 years ago. I also added some references to changes I already documented but that had no prior GH issue.

I suggest to anyone in need of a migration guide should just fork v4 instead or find some other fork / re-implementation.

[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]

#814

[ghost]

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.

[ghost]

@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