[RFC] - Route guards

[StarpTech]

Feature request

Goals

In Next.js, any user can navigate anywhere in the application anytime. That's not always the right thing to do.

• Perhaps the user is not authorized to navigate to the target component.
• Maybe the user must login (authenticate) first.
• Maybe you should fetch some data before you display the target component.
• You might want to save pending changes before leaving a page component.
• You might ask the user if it's OK to discard pending changes rather than save them.

We need an abstraction to handle these use cases in a proper way.

Describe the solution you'd like

The router should have the capabilities to define such guards. In a guard, the current router information and the target path must be provided. Therefore we need access to the application state (_app props?).

There are different types of guards:

• guard will fire on entering and leaving transition
• canLoadGuard will fire only when the user navigates to a different page.
• canLeaveGuard will fire only when the user leaves the current page.

async function authGuard({ next: RouteSnapshot, state: RouterState }) {
	return true 	// navigation process continues
	return false 	// navigation process stops
    return '/login' // navigation redirect to login route
	return {pathname: '/login', props: {} } // passing additional props to the target component
   
	throw new Error() 		 	// abort and show error page
	
}
Router.guards | Router.canLoadGuards | Router.canLeaveGuards
Router.guards.add('*', authGuard, ...); // for all pages, guards executed sequentially.
Router.guards.add('/dashboard', authGuard, ...); // only for page with path 'dashboard'
Router.guards.add('/dashboard/*', authGuard, ...); // only for sub-pages of dashboard
Router.guards.add('*', [authGuard, guard2]); // for all pages, guards executed in parallel.

Describe alternatives you've considered

The current alternatives are:

Use a HOC for every page to act as a guard. While it works it is far from great:

• We have to check that on render time not before the router initiates a route change. This results in unnecessary renders or even API requests.
• We have to repeat us on every page.
• An unnecessary download of resources because the user is navigated at first to the wrong route.

Look at the HOC below. We return null in case of an unauthenticated user. This will result in huge flickering because the page is not hydrated.

Example

As an example, let watch Zeit.co dashboard. The issue was solved gracefully but it demonstrates the issue very well.

export default (Page) => (pageProps) => {
  const router = useRouter();
  const isAuthenticated = useIsAuthenticated();
  const [, dispatch] = useAppStore();
  const { data } = useUserProfile();

  useEffect(() => {
    if (!isAuthenticated) {
      router.push('/login');
    }
  }, [isAuthenticated]);

  useEffect(() => {
    if (isAuthenticated && data) {
      dispatch({ type: 'updateUser', data });

      if (data.registeredAt === null) {
        router.push('/register');
      }
    }
  }, [data]);

  if (isAuthenticated) {
    return <Page {...pageProps} isPrivate />;
  }

  return null;
};

Following Next.js examples illustrate the need for such an abstraction:

• Hard page refresh in fetch implementation. This will destroy all SPA benefits.
  https://github.com/zeit/next.js/blob/46ecb00112b1d667c23399038874148f6eb80f49/examples/auth0/lib/user.js#L57

• HOC with localStorage hack
  https://github.com/zeit/next.js/blob/46ecb00112b1d667c23399038874148f6eb80f49/examples/with-cookie-auth-fauna/utils/auth.js#L16
  https://github.com/zeit/next.js/blob/46ecb00112b1d667c23399038874148f6eb80f49/examples/with-cookie-auth/utils/auth.js#L34

• Conditional rendering, same drawbacks like the HOC and not easy to adopt on many pages.
  https://github.com/zeit/next.js/blob/46ecb00112b1d667c23399038874148f6eb80f49/examples/with-firebase-authentication/pages/index.js#L37

Problems to solve

• How is page data communicated?
• How can we ensure that we don't waste time? "Render as you Fetch Pattern"
• Implement it with suspense in mind?

Additional context

• https://angular.io/guide/router#milestone-5-route-guards
• Excellent article by @kentcdodds about bad usage of the client-side redirect

Related

• Route cancellation #2476
• Detect when user leaves the page #9662
• How to redirect? #4931

Thanks!

[NateRadebaugh]

Since routing is file-system based and each page is handled separately in the nextjs hybrid approach, I'd imagine the API may be better suited to live at the per-page level, similar to getStaticProps, etc. instead of in a single site-wide location.

That being said, once #9081 lands, there may be some precedence/overlap for parts of this feature and global pattern you're describing. I'm curious how the maintainers view the "guards" idea in the greater scheme.

[StarpTech]

Hi, @NateRadebaugh thanks for stepping in.

Since routing is file-system based and each page is handled separately in the nextjs hybrid approach, I'd imagine the API may be better suited to live at the per-page level, similar to getStaticProps, etc. instead of in a single site-wide location.

I see it more like a "router" configuration rather than a page configuration. This is similar to a HTTP API. Imagine, expressjs. Rather than add the auth middleware to every API route you would define default middlewares for a specific path. This fits very well for Next.js because it operates on the file-system.

In that way, you have the greatest flexibility.

[StarpTech]

That being said, once #9081 lands, there may be some precedence/overlap for parts of this feature and global pattern you're describing. I'm curious how the maintainers view the "guards" idea in the greater scheme.

Not sure, how it should be fixed by defining rewrites or redirects. The logic of the issues usually sits in the frontend code and can start with no server in touch. We also don't want lose the SPA feeling.

[NateRadebaugh]

Thanks, that makes sense!

[eric-burel]

It seems that those questions, in a form or another, are recurring. You may be interested in:

• Protecting routes with getServerSideProps #16724
• What is the point of SSR these days? #10437 (comment)
• next export with getServerSideProps #15674
• Provide a mechanizm to disable SSR #4381 (SSR prevents you from using end-to-end frameworks like Cypress efficiently)
• [RFC] - Route guards #11822
• RFC: Custom Routes #9081
• RFC: Returning redirects from getServerSideProps / getStaticProps #14890

Specifically, community is inventing all sorts of anti-pattern or (hopefully) valid patterns to circumvent the lack of a core feature that would allow you to check auth before accessing a route.

[dolie]

Just linking... #18291

[jembach]

Hi,

in an other discussion i have provided a similar solution based on per route middleware: #18832 (comment)

[jamietdavidson]

Your proposed solution is exactly what I am looking for.

Has anyone found an elegant solution?

[tubbo]

The new special files in Next 13 provide an opportunity here for implementing this cleanly, as well as enabling API routing and middleware within the new app dir.

One could imagine a middleware.ts in a route segment, which would look like an API route:

// app/api/foo/middleware.ts
import { NextResponse } from 'next/middleware'

export default function handler() {
  return NextResponse.status(200)
}

The rule could be that if the function returns a response, stop everything and just use that as the response. Otherwise, treat the function as a middleware and keep on rendering the page:

import { NextRequest } from 'next/middleware'

export default function handler() {
  if (NextRequest.headers('Authorization')) {
    NextRequest.setCookie('token', NextRequest.headers('Authorization'))
  }
}

The benefits here would be:

• One API to rule them all for writing serverless request handler functions, even down to the new params prop in server components.
• Leverage route segment hierarchy to obviate the path matching that one has to do today with edge middleware
• Route guarding, as mentioned in the OP
• API routes could now be at any path. You no longer need to isolate your handlers in /api/ and configure rewrites for things like dynamic feeds.