Migrating from React Router

This guide will help you understand how to transition from React Router to file-system based routes with Next.js. Using next/link and next/router will allow you to:

  • Decrease bundle size by removing React Router as a dependency.
  • Define your application routes through the file system.
  • Utilize the latest improvements to the Next.js framework.

Basics

First, uninstall React Router. You’ll be migrating to the built-in routing with Next.js.

  1. npm uninstall react-router-dom

The Link component for performing client-side route transitions is slightly different from React Router.

  1. // Before (React Router)
  2. import { Link } from 'react-router-dom'
  4. export default function App() {
  5.   return <Link to="/about">About</Link>
  6. }
  8. // After (Next.js)
  9. import Link from 'next/link'
  11. export default function App() {
  12.   return (
  13.     <Link href="/about">
  14.       <a>About</a>
  15.     </Link>
  16.   )
  17. }

Most React applications that use React Router have a top-level navigation file, containing a list of routes. For example:

  1. import { BrowserRouter as Router, Switch, Route } from 'react-router-dom'
  3. export default function App() {
  4.   return (
  5.     <Router>
  6.       <Switch>
  7.         <Route path="/about">
  8.           <h1>About</h1>
  9.         </Route>
  10.         <Route path="/blog">
  11.           <h1>Blog</h1>
  12.         </Route>
  13.         <Route path="/">
  14.           <h1>Home</h1>
  15.         </Route>
  16.       </Switch>
  17.     </Router>
  18.   )
  19. }

With Next.js, you can express the same application structure in the file system. When a file is added to the pages directory it’s automatically available as a route.

  • pages/about.js → /about
  • pages/blog.js → /blog
  • pages/index.js → /

Nested Routes

In the example below, routes like /blog/my-post would render the Post component. If a slug was not provided, it would render the list of all blog posts.

  1. import {
  2.   BrowserRouter as Router,
  3.   Switch,
  4.   Route,
  5.   useRouteMatch,
  6.   useParams,
  7. } from 'react-router-dom'
  9. export default function Blog() {
  10.   // Nested route under /blog
  11.   const match = useRouteMatch()
  13.   return (
  14.     <Router>
  15.       <Switch>
  16.         <Route path={`${match.path}/:slug`}>
  17.           <Post />
  18.         </Route>
  19.         <Route path={match.path}>
  20.           <h1>All Blog Posts</h1>
  21.         </Route>
  22.       </Switch>
  23.     </Router>
  24.   )
  25. }
  27. function Post() {
  28.   const { slug } = useParams()
  29.   return <h1>Post Slug: {slug}</h1>
  30. }

Rather than using the :slug syntax inside your Route component, Next.js uses the [slug] syntax in the file name for Dynamic Routes. We can transform this to Next.js by creating two new files, pages/blog/index.js (showing all pages) and pages/blog/[slug].js (showing an individual post).

  1. // pages/blog/index.js
  3. export default function Blog() {
  4.   return <h1>All Blog Posts</h1>
  5. }
  7. // pages/blog/[slug].js
  9. import { useRouter } from 'next/router'
  11. export default function Post() {
  12.   const router = useRouter()
  13.   const { slug } = router.query
  15.   return <h1>Post Slug: {slug}</h1>
  16. }

Server Rendering

Next.js has built-in support for Server-side Rendering. This means you can remove any instances of StaticRouter in your code.

Code Splitting

Next.js has built-in support for Code Splitting. This means you can remove any instances of:

  • @loadable/server, @loadable/babel-plugin, and @loadable/webpack-plugin
  • Modifications to your .babelrc for @loadable/babel-plugin

Each file inside your pages/ directory will be code split into its own JavaScript bundle during the build process. Next.js also supports ES2020 dynamic import() for JavaScript. With it you can import JavaScript modules dynamically and work with them. They also work with SSR.

For more information, read about Dynamic Imports.

Scroll Restoration

Next.js has built-in support for Scroll Restoration. This means you can remove any custom ScrollToTop components you have defined.

The default behavior of next/link and next/router is to scroll to the top of the page. You can also disable this if you prefer.

Learn More

For more information on what to do next, we recommend the following sections:

RoutingLearn more about routing in Next.js.

Dynamic RoutesLearn more about the built-in dynamic routes.

PagesEnable client-side transitions with next/link.