[Feature]: allow providing `history` object when calling `createBrowserRouter()`

[jorroll]

What is the new or updated feature that you are suggesting?

The new createBrowserRouter() API internally calls createBrowserHistory() but doesn't provide a way for end-users to get access to the created history object if we'd like to subscribe to history events. I'd like the ability to instantiate createBrowserHistory() myself and provide the history object as an option to createBrowserRouter(). Using the old, v6.3 api, doing something like this was possible via the unstable_HistoryRouter.

It seems likely that something along these lines is already planned, but there doesn't appear to be a tracking issue for this feature.

I actually tried using the internal API myself to implement a custom createBrowserRouter() and provide my own createBrowserHistory() to it (using the new createBrowserHistory export from "@remix-run/router", but

1. history.listen() only accepts a single listener
2. If I work around #1 and monkeypatch the history object to accept multiple listeners, it doesn't appear as though the listener is ever actually called (perhaps this is a placeholder method which isn't fleshed out yet? Obviously this is internal API at the moment so I'm not surprised things aren't working yet).

Why should this feature be included?

I'd like to subscribe to history events and respond to them within my application--both before and after react router receives these events (e.g. maybe I want to cancel an event before it reaches React Router).

[ChristophP]

I'm have a similar need to listen to history changes for other parts of the app on the same page that aren't written in React.
Related #9385

[Mikilll94]

Yeah, this is really needed to be able to navigate outside of React components.

[sergioavazquez]

Being able to navigate outside React components is a key feature. Please add this back as I'm stuck on v6.3 on several projects until you do.

[yangoff]

i'm stuck too, please, it is imprescindible

[ChristophP]

Yes, please Shopify :-) https://remix.run/blog/remixing-shopify

[brophdawg11]

Hey folks! There's a bunch of separate issues around navigating from outside the react tree in 6.4, so I choose this one as the de-facto "source of truth" issue 🙃. I'll drop an answer here and then link off to it from as many other issues as I can find. Let's try to centralize further discussion here if we can so we don't miss anything!

There's some nuance here based on the version you're using so I'll try my best to provide a clear explanation of the paths forward.

Folks on 6.0 through 6.3

For those of you using unstable_HistoryRouter in 6.0->6.3, that was dropped from the updated docs but it's still there and you can still use it (with the same warnings as before). It's not considered stable and is open to breaking in the future.

Folks on 6.4+ but not using a Data Router

If you've upgraded to 6.4+ but aren't using a data router, then you can also still use unstable_HistoryRouter but there are some nuanced changes to the way we interface with window.history internally. Your best bet is probably just to add history@5 as your own dependency and import createBrowserHistory from there.

You can try using the createBrowserHistory from react-router-dom@6.4 but you will need to instantiate it as createBrowserHistory({ v5Compat: true }) to opt-into the v5 behavior. The newer version also currently doesn't allow multiple listeners since it wasn't intended for external consumption, so it's only really useful for navigating from outside the react tree, but not listening for updates from outside the tree. If you need that then go with history@5.

Folks on 6.4+ using a Data Router (RouterProvider)

🎉 Congrats on upgrading to the new data routers and we hope you're loving the UX improvements you can get from loaders/actions/fetchers! If you're still in need of a way to navigate or respond to updates from outside the react tree, then there's both good and bad news!

The good news is that you can just do it manually via the router instance you get from createBrowserRouter! By introducing data APIs, history is really just an implementation detail now and the router is the entry point. This is because we have to fetch data prior to routing so we can't just respond to history events anymore.

let router = createBrowserRouter(...);

// If you need to navigate externally, instead of history.push you can do:
router.navigate('/path');

// And instead of history.replace you can do:
router.navigate('/path', { replace: true });

// And instead of history.listen you can:
router.subscribe((state) => console.log('new state', state));

Now, for the bad news 😕 . Just like unstable_HistoryRouter we also consider this type of external navigation and subscribing to be unstable, which is why we haven't documented this and why we've marked all the router APIs as @internal PRIVATE - DO NOT USE in JSDoc/Typescript. This isn't to say that they'll forever be unstable, but since it's not the normally expected usage of the router, we're still making sure that this type of external-navigation doesn't introduce problems (and we're fairly confident it doesn't with the introduction of useSyncExternalStore in react 18!)

If this type of navigation is necessary for your app and you need a replacement for unstable_HistoryRouter when using RouterProvider then we encourage you use the router.navigate and router.subscribe methods and help us beta test the approach! Please feel free to open new GH issues if you run into any using that approach and we'll use them to help us make the call on moving that towards future stable release.

Thanks folks!

Also w.r.t. this specific issue I'm going to close it as I think the router provides the behavior you need, however please note that you cannot cancel these events - subscribe will be called after the navigations.

I'd like to subscribe to history events and respond to them within my application--both before and after react router receives these events (e.g. maybe I want to cancel an event before it reaches React Router).

If you're looking to cancel an event then that's a different thing - please check out this comment and follow along in that issue - but I don't think we'll be bringing blocking back into v6 since it's always been a bit of a hacky implementation (since you cannot "block" a back/forward navigation from the browser).

[yann-combarnous]

Folks on 6.4+ but not using a Data Router

If you've upgraded to 6.4+ but aren't using a data router, then you can also still use unstable_HistoryRouter but there are some nuanced changes to the way we interface with window.history internally. Your best bet is probably just to add history@5 as your own dependency and import createBrowserHistory from there.

@brophdawg11, thx for the explanation. I tried this approach, and I am getting typescript error:

Property 'encodeLocation' is missing in type 'BrowserHistory' but required in type 'History'.ts(2741)

So it seems like this approach is broken due to the new "encodeLocation" requirement for History.

[brophdawg11]

Ah - thanks for calling this out - that's a new 6.4-only thing. Does everything work fine if you ignore that with // @ts-expect-error? That encodeLocation method is new in the internal history and only used in <RouterProvider> so it shouldn't ever be referenced if you're using unstable_HistoryRouter

[yann-combarnous]

Ah - thanks for calling this out - that's a new 6.4-only thing. Does everything work fine if you ignore that with // @ts-expect-error? That encodeLocation method is new in the internal history and only used in <RouterProvider> so it shouldn't ever be referenced if you're using unstable_HistoryRouter

Thanks @brophdawg11 , yes silencing TS error works, but may miss future issues. What about adding the new method to "history" package as well and bump to 5.4.0 ? This will be smoother for transition, IMO.