Skip to main content

Next.js Routing Guide

Next.js provides the ability to do universal routing, meaning that inbound HTTP requests cause specific pages to be rendered and served up, and you can create hyperlinks among pages where clicking on them allows you to transition among pages without provoking a full page reload. We recommend familiarizing yourself with the official Next.js documentation, but we'll touch on core concepts here as well.

Automatic file system routing​

The simplest way to define routes in your application is to simply export components from files in a pages/ directory in your application. The structure of this directory and file names directly map to route names. For example, given this structure:

pages/
  blog/
    index.js
    1.js
    2.js
  about.js
  index.js

...the following route URLs are available for your site:

/                       // maps to /pages/index.js
/about                  // maps to /pages/about.js
/blog                   // maps to /pages/blog/index.js
/blog/1                 // maps to /pages/blog/1.js
/blog/2                 // maps to /pages/blog/2.js

Client-side transitions among pages​

To create hyperlinks to pages that utilize client-side routing:

import * as React from 'react';
import Link from 'next/link';

const MyComponent = () => (
  <Link href="/blog">
    <a>Blog</a>
  </Link>
);

Note that unlike most React routing frameworks, the Link component doesn't render the hyperlink directly, but rather it modifies the href prop of its child component.

You can also programmatically change routes with the Next.js router. Consult the Next.js routing docs for more information.

Parameterized pages​

If you need the contents of the page to be dynamic based on the URL, you can read the query string or use dynamic routes. There are two ways to read the query string. At the page level, the context object passed to the static getInitialProps method contains a query object with the parsed query string parameters.

import * as React from 'react';
import fetchArticle from './fetch-article';

export default class BlogPage extends React.Component {
  static async getInitialProps({ query }) {
    const contents = await fetchArticle(query.article);

    return {
      articleMarkdown: contents
    }
  }
  
  render() {
    const content = this.props.articleMarkdown;
    return <>{ content }</>
  }
};

If you need to access router details in a more nested context, you can connect your component with the Next.js router HOC: withRouter.