Utils - NextJS

The @eds/utils-nextjs package contains utils to help integrate NextJS with some of our tools and deployment methods.

The useNextClientRouter hook can be used to have a statically-exported NextJS site handle routing like react-router.

NextJS deploys as a multi-page-app but gives a single-page-app experience once the page is loaded. This means, out of the box NextJS won't handle routing when:

• The app is exported to S3 with all paths routed to the root index.html page.
• When embedded inside a twig template.

useNextClientRouter can be used to handle these cases. It uses NextJS' useRouter hook to handle all routing through NextJS.

The useNextClientRouter should be used with the DisableSSR function, also provided by the @eds/utils-nextjs package, to avoid any hydration mismatches.

const Homepage: NextPage = () => {
  const loading = useNextClientRouter();
  return <>{loading ? <Loading /> : <div>Welcome to my homepage!</div>}</>;
};

export default DisableSSR(Homepage);

useNextClientRouter also handles routing unknown urls to a 404 page. By default it routes to /404.

This can be changed by passing a different path to useNextClientRouter's options.

const Homepage: NextPage = () => {
  const loading = useNextClientRouter({ notFoundRoute: '/page-not-found' });
  return <>{loading ? <Loading /> : <div>Welcome to my homepage!</div>}</>;
};

export default DisableSSR(Homepage);

Some setup is required to get Emotion working with server-side rendering (SSR). This package has some helpers for getting SSR setup in NextJS sites.

If you need to get SSR working in a non-NextJS site head to the Emotion SSR documentation for implementation details.

The <EmotionSSRDocument /> component is the easiest way to get Emotion SSR in a NextJS site.

It is suitable when you don't need any customisation in your _document.tsx page. If you require a custom _document.tsx page see injectEmotionStylesIntoNextDocument.

• In your project directory run npm i @eds/utils-nextjs.
• Create an empty _document.tsx file in your pages directory.
• Add the following code to your _document.tsx file:

import { EmotionSSRDocument } from '@eds/utils-nextjs';
export default EmotionSSRDocument;

The injectEmotionStylesIntoNextDocument util lets you setup server-side rendering for Emotion on a NextJS site where you have a custom _document.tsx page.

To use it add a getInitialProps function that implements injectEmotionStylesIntoNextDocument as follows.

When _document.tsx is a functional component:

import NextDocument, { Html, Head, Main, NextScript, DocumentContext, DocumentInitialProps } from 'next/document';
import { injectEmotionStylesIntoNextDocument } from './next-document-server-emotion';

export const Document = () => {
  /* Your custom Document component */
};

Document.getInitialProps = async (context: DocumentContext): Promise<DocumentInitialProps> => {
  const initialProps = await NextDocument.getInitialProps(context);
  return injectEmotionStylesIntoNextDocument(initialProps);
};

When _document.tsx is a class component:

import NextDocument, { Html, Head, Main, NextScript, DocumentContext, DocumentInitialProps } from 'next/document';
import { injectEmotionStylesIntoNextDocument } from '@eds/utils-nextjs';

export default class Document extends NextDocument {
  static async getInitialProps(context: DocumentContext): Promise<DocumentInitialProps> {
    const initialProps = await NextDocument.getInitialProps(context);
    return injectEmotionStylesIntoNextDocument(initialProps);
  }

  render() {
    /* Your custom Document component */
  }
}