The Future of React Router and @reach/router

tl;dr

• We are bringing together the best of React Router and Reach Router into a new, hook-based API.
• React Router will be the surviving project.
• We'll introduce this API in a minor release (5.x). That means it's 100% backward compatible. (Don't forget, we recently released React Router v5, it was a major version change only because of a dependency version range issue, there were no API changes.)
• We will continue to support @reach/router 1.0 with bugfixes

Background

Five years ago Michael and I built the first version of React Router (!). When we released version 4 two years ago we said we wouldn't change anything about the API unless React itself fundamentally changed. Two years later and we haven't 😘. But now, with the introduction of hooks, React has fundamentally changed how we can compose state and behavior, and we want to take advantage of it.

Taking these new tools (and things we've learned from starting fresh in @reach/router) we've created a smaller, smarter, and simpler routing utility. We think you'll love it.

We don't have a release ready yet (we're still on our workshop tour) but we wanted to let everybody know what's coming, and what it means for you and your team.

Which Project Should I Choose Today?

React Router will offer an incremental migration path, but @reach/router looks slightly more like the new API. So:

• If you only have a few routes you may want to pick @reach/router. The @reach/router API looks slightly more like the new API so it'll be easier to migrate in one commit. It shouldn't take more than an afternoon.

• If you have a lot of routes, especially with a lot of nested Route and Switch components, you may want to pick React Router. It will be 100% backward compatible, offering an incremental migration path to the new hook-based APIs.

• The current APIs of React Router and @reach/router will be supported for the foreseeable future with bugfixes (just like how we have quietly maintained React Router v3 for the last few years). So, if the new stuff isn't compelling, you won't need to update anything.

I'm Using @reach/router, Now What?

We will continue to support @reach/router 1.0 with bugfixes for the foreseeable future, so you don't need to do anything for a long time if you don't want to.

If the new API interests you however, the migration should be pretty straightforward. The next React Router API, on the surface, looks more like @reach/router than React Router. Most of the changes have a one-to-one mapping between both APIs and some are identical.

Because of this, we don't recommend switching to React Router in preparation for the hook-based API. You'll have an easier time migrating from your current code.

I'm Using React Router, Now What?

The next API is backward compatible and opt-in. We will continue to maintain the v5 API for the foreseeable future, so you don't have to do anything for a long time if you don't want to.

If you would like to take advantage of the new API, you will be able to migrate incrementally. It'll work something like this:

1. Pick one of your deepest Route or Switch components
2. Update the API

The migrated section of the app now has access to the new APIs while the rest of the app will continue to work as it did before, without any changes. Continue this until the whole app is migrated--or don't. You can start new features of your app with new features of React Router without having to change any of your other routing code.

Features

Here's a run-down of a few of the features we're excited about:

• Smaller bundle. Current size of the Router dependency in a fully migrated app is around 3kb
• Built of composable parts. Simple apps don't need everything.
• Smart path matching, no more messing around with the order of your routes or exact props
• Nested Route Configs (much like v3 and @reach/router)
• Relative Links, navigation, and routes
• Access route data with useParams() from anywhere below the route
• Access to location and navigate with useLocation() anywhere in the app.
• Route parameter validation
• Route matching on location state
• Automatic focus management on route transitions
• Concurrent/Suspense Ready

Code Samples

Here's a sneak peek at some of the new API.

// with relative links you can change the query string easily
// without having to reconstruct the current URL
<Link to="?something=different"/>

// Or link deeper, assuming you're at `/users/123` you can link
// to `/users/123/account/reset-password` with:
<Link to="account/reset-password" />

// useLocation makes navigation-based side-effects a breeze
function usePageViews() {
  const { location } = useLocation()
  useEffect(() => {
    ga('send', 'pageview', location.pathname)
  }, [location])
}

// You can access params with a hook
// (much friendlier for TypeScript, too)
function SomeComponent() {
  const { userId } = useParams()
  // ...
}

// With the new route ranking algorithm, we're able to validate routes
// as they are matching the location. If `validate` returns false, the
// route acts as if the path didn't match the location at all
<Route
  path="event/:date"
  validate={params => isValidDate(params.date)}
>
  <Event/>
</Route>

Timeline

We will be updating the 5.x Roadmap with these new items and get some estimated release dates from there.

Thanks!