Developer Quality Of Life Improvement (A series of improvements to Next.js) - Layouts, Middlewares, Error Pages, Validations

[ConsoleTVs]

First of all, I want to thank all the people involved in this amazing project. I find most of the decisions and features over the last
year to be amazing and I'm very exited for the direction the project is heading to. That said, I would like to propose a few
quality of life improvements for all the developers that use Next.js.

I will now propose a few features that Next.js could have in future releases to improve the development experience. Please don't hesitate to leave feedback on all topics presented.

Layouts

Most websites and web apps often have a common layout shared across multiple pages. Currently, Next.js does offer an option to modify the base _app and _document of the page. However, this have limitations and it's still not good enough for all cases.

More info: https://adamwathan.me/2019/10/17/persistent-layout-patterns-in-nextjs/

Current solutions

Wrap each page with a <Layout> component

• ❌ Requires to import <Layout> on each page.
• ❌ Not persistent between pages with the same layout (<Layout> is disposed and re-renderer each navigation even if both pages have the same <Layout>.

// pages/index.ts

import type { NextPage } from 'next'
import Layout from 'lib/layouts'

const Page: NextPage = () => (
  <Layout>
    <div>...</div>
  </Layout>
)

export default Page

Add a common <Layout> to the _app

• ❌ Requires all the pages of the Next.js application to have the same layout.
• ✔️ Persistent layout between page navigations (The component is re-used without re-rendering).

// pages/_app.ts

import type { AppProps } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  )
}

export default MyApp

// pages/index.ts

import type { NextPage } from 'next'

const Page: NextPage = () => (
  <div>...</div>
)

export default Page

Add a dynamic <Layout> to the _app using a static property.

• ❌ Requires to import the layout on each page (Note: You can also set the property to a string and select the layout on _app based on it).
• ❌ Requires adding properties to the component, throws type-errors on Typescript.
• ❌ Top level layout is changed when using nested layouts (check: https://adamwathan.me/2019/10/17/persistent-layout-patterns-in-nextjs/ - option 3)
• ✔️ Pages are not required to share the same layout and can be changed per page.
• ✔️ Persistent layout between page navigations (The component is re-used without re-rendering).

// pages/_app.ts

import type { AppProps } from 'next/app'
import MainLayout from 'lib/layouts'

function MyApp({ Component, pageProps }: AppProps) {
  const Layout = Component.layout ?? MainLayout
  return (
    <Layout>
      <Component {...pageProps} />
    </Layout>
  )
}

export default MyApp

// pages/index.ts

import type { NextPage } from 'next'
import Layout from 'lib/layouts'

const Page: NextPage = () => (
  <div>...</div>
)

// Throws type-error: Page has no .layout property.
Page.layout = Layout // could potentially be a string and select it on `_app`

export default Page

Add a dynamic <Layout> to the _app using a function.

• ❌ Requires to import the layout on each page (note: Can also be abstracted into a string map and find the corresponding function at _app).
• ❌ Requires adding properties to the component, throws type-errors on Typescript.
• ✔️ Top level layout is not changed when using nested layouts (check: https://adamwathan.me/2019/10/17/persistent-layout-patterns-in-nextjs/ - option 4)
• ✔️ Pages are not required to share the same layout and can be changed per page.
• ✔️ Persistent layout between page navigations (The component is re-used without re-rendering).

// pages/_app.ts

import type { AppProps } from 'next/app'
import Layout from 'layouts/main'

function MyApp({ Component, pageProps }: AppProps) {
  const layout = Component.getLayout ?? (page) => page
  return layout(<Component {...pageProps} />)
}

export default MyApp

// pages/index.ts

import type { NextPage } from 'next'
import Layout from 'layouts/main'

const Page: NextPage = () => (
  <div>...</div>
)

// Throws type-error: Page has no .getLayout property.
Page.getLayout = (page) => <Layout>{page}</Layout>

export default Page

Add a dynamic <Layout> to the _app using a getStaticProps.

• ❌ Makes use of the static props and can't use functions / components on it since it needs to be serializable.
• ✔️ Top level layout is not changed when using nested layouts (check: https://adamwathan.me/2019/10/17/persistent-layout-patterns-in-nextjs/ - option 4)
• ✔️ Pages are not required to share the same layout and can be changed per page.
• ✔️ Persistent layout between page navigations (The component is re-used without re-rendering).

// pages/_app.ts

import type { AppProps } from 'next/app'
import myLayouts from 'lib/layouts'

// PageProps is an interface with the available props (like layout: string)
// layouts is just an object / map holding a reference from string to Layout a function
import { PageProps, layouts } from 'lib/pages'

function MyApp({ Component, pageProps }: AppProps<PageProps>) {
  const layout = myLayouts[pageProps.layout] ?? (page) => page
  return layout(<Component {...pageProps} />)
}

export default MyApp

// pages/index.ts

import type { NextPage } from 'next'
import type { PageProps } from 'lib/pages'

const Page: NextPage = () => (
  <div>...</div>
)

export const getStaticProps: GetStaticProps<PageProps> = async (context) => ({
  props: {
    layout: 'main',
  },
})

export default Page

Proposed solutions

The proposed solution goes around using existing ways of defining getStatcProps functions in pages.

My suggestion is to export a getLayout function or property. This should be the type of it:

type NextLayout<T extends string = ''> = undefined | (component: Component) => NextLayoutFunction | T

// pages/index.ts

import type { NextPage } from 'next'
import Layout from 'layouts/main'

const Page: NextPage = () => (
  <div>...</div>
)

// Using a function (requires importing the Layout component on each page.
export const getLayout: NextLayout = (page) => <Layout>{page}</Layout>
// Using a string with the AvailableLayouts generic parameter to have type-safety.
// This type CAN be exported and abstracted in another file to just import it like:
// import type { MyLayout } from 'lib/layouts'
// export const getLayouts: MyLayouts = 'main'
// This would require some discussion about how those would be applied.
export const getLayout: NextLayout<AvailableLayouts> = 'main'

export default Page

_app option 1

// pages/_app.ts

import type { AppProps } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  // Component here does already contain the layout applied internally.
  return <Component {...pageProps} />
}

export default MyApp

_app option 2

// pages/_app.ts

import type { AppProps } from 'next/app'

function MyApp({ ComponentLayout, Component, pageProps }: AppProps) {
  // ComponentLayout here does already contain the component specific layout applied internally.
  // or a ({ children }) => children component as the default
  return (
    <ComponentLayout>
      <Component {...pageProps} />
    </ComponentLayout>
  )
}

export default MyApp

Ability to setup nested _app pages

The hability of adding multiple nested _app pages is also of great interest, there may also be that all subpages of a given path use the same sub-layout or even a complete different layout.

path -> layout

example.com/* -> main
example.com/blog/* -> blog
example.com/subpage/* -> main -> subpage

The best way would be to use the 2nd option of the layouts solution since it allows you to completly drop the layout behind you. Otherwise, it will always be nested. Therefore, the following files could correspond to the 3 paths given above:

// pages/_app.ts

import type { AppProps } from 'next/app'
import MainLayout from 'layouts/main'

function MyApp({ ComponentLayout, Component, pageProps }: AppProps) {
  return (
    <MainLayout>
      <ComponentLayout>
        <Component {...pageProps} />
      </ComponentLayout>
    <MainLayout>
  )
}

export default MyApp

// pages/blog/_app.ts

import type { AppProps } from 'next/app'
import BlogLayout from 'layouts/blog'

function MyApp({ ComponentLayout, Component, pageProps }: AppProps) {
  return (
    <BlogLayout>
      <ComponentLayout>
        <Component {...pageProps} />
      </ComponentLayout>
    </BlogLayout>
  )
}

export default MyApp

// pages/subpage/_app.ts

import type { AppProps } from 'next/app'
import SubPageLayout from 'layouts/subpage'

function MyApp({ ComponentLayout, Component, pageProps }: AppProps) {
  return ( 
    <SubPageLayout>
      <ComponentLayout>
        <Component {...pageProps} />
      </ComponentLayout>
    </SubPageLayout> 
  )
}

export default MyApp

In this last one however, there's _app in pages/_app and pages/subpage/_app. The first _app is rendered with the
following information:

• ComponentLayout: ({children}) => children This is needed because the subpage _app will already define where the component layout is located and we should not repeat it. This pretty much makes that component dissapear.
• Component: The component is replaced with MyApp from subpage/_app

The result is then:

<MainLayout> 
  <SubPageLayout>
    <ComponentLayout>
      <Component {...pageProps} />
    </ComponentLayout>
  </SubPageLayout>  
<MainLayout>

Middlewares

Middlewares are also very common between pages, without looking further, most web application use some sort of authentication.

Current solutions

The only way to apply middleware to pages is currently to use a React technique that used HOC components to achieve it. For example, you may define a HOC auth component like:

// lib/auth/index.ts

export function auth<P>(Component: NextComponentType<NextPageContext, {}, P>) {
  return (props: P) => {
    // Do something with authentication
    return <Component {...props} />
  }
}

Then apply it to the page like:

// pages/index.ts

import type { NextPage } from 'next'
import { auth } from 'lib/auth'

const Page: NextPage = () => (
  <div>...</div>
)

export default auth(Page)

This introduces 2 main concerns:

• Nested middlewares start to get messy.

// pages/index.ts

import type { NextPage } from 'next'
import { auth, someOther, maybeAnother } from 'lib/middlewares'

const Page: NextPage = () => (
  <div>...</div>
)

export default auth(someOther(maybeAnother(Page)))

• The need to import each middleware manually.

Proposed solutions

// pages/index.ts

import type { NextPage } from 'next'
import { auth, someOther, maybeAnother } from 'lib/middlewares'

const Page: NextPage = () => (
  <div>...</div>
)

// Allow for the middlewares to be applied in order, from a native list
// rather than applying them directly to the component page.
export const getMiddlewares = [auth, someOther, maybeAnother]
// Additionally, allowing them to be specified by string and defined somewhere else.
// This would allow you to completly drop the imports.
// This would require some discussion about how those would be applied.
export const getMiddlewares = ['auth', 'someOther', 'maybeAnother']

export default Page

Error Pages

Next.js currentnly only supports custom 404 and 500 pages. My suggestion here is to just allow arbitrary number of errors to be handled correctly on the front-end. For example; a 403, 405 HTTP error codes are also common, or even 422 for invalid request parameters (like invalid dynamic data, see validation chapter below, like /user/invalid-user-id123). I would recommend to just use the current pages structure and allow the dev to add files like what's already done with 404.js. So if the dev wants to add a 405 page: pages/405.js. Ideally I would recommend to have a specific errors page, but this is a good enough solution.

Validation

Similar to Nuxt.js validation, allowing a page to have a validation phase (sort of as a middleware) will allow us to have a specific place to check for invalid request parameters or invalid properties to the page (as mentioned above, an invalid user ID for example).

// pages/index.ts

import type { NextPage } from 'next'
import { auth, someOther, maybeAnother } from 'lib/middlewares'

const Page: NextPage = () => (
  <div>...</div>
)

export const validate = async ({ context, pageProps }) => {
  // true -> navigation accepted
  // false -> navigation canceled, throw 422 ?
  return true;
}

export default Page

[ConsoleTVs]

Related to Layouts: #8193