The Complete Guide to Higher-Order Components in Next.js React With Typescript

I always wondered that why the official react dev has removed the part of HOCs from it's documentation until I seek and found the answer in it's legacy docs:

'Higher-order components are not commonly used in modern React code' — official react dev

Now, we can only access the legacy docs to view it but sadly with it's old but gold obsolete class syntax.

W3schools is another alternative(with only 1 example which is insufficient to grasp things) alongside the indie blogs. So far, I've seen that the given portion of the contents wasn't included, whether in typescript or in a concrete deep dive.

Just because of my curiosity, I've gone through and grasp every use case of React HOCs, every potential replacement for HOCs, every tricks to remove the unnecessary workarounds for the app that might be a good fit for HOCs. I assure you, you're going to have A LOT of takeaways by the end of this article and maybe refute the claim of react docs(see above) — who knows?

Concretely, "a higher-order component is a function that takes a component and returns a new component" says the legacy docs. When we apply a HOC to a component, though, the original component is wrapped with a dedicated container component.

The HOCs are commonly used for:

• Authentication
• Validation
• Redirection
• Database Queries/Actions

Pretty much everything on the server. But I'd like to encourage you to use it widely not only on the server side but the client side as well. Add it on your checklist I addressed about that later on as well.

When it comes to using a HOC with typescript, everything slightly changes due to the nature of .tsx syntax. I want you to never forget the first rule I understood so far — We always need to consider of the given and taken props.

The most basic way to digest underlying behavior of the HOCs passes throughout the very common usage scenario of the HOC which is the authorization. Suppose that we're working on this directory inside a latest version of Next.js/React app:

1app/
2├── layout.tsx
3├── page.tsx
4├── profile
5│   └── [userId] // dynamic slug  
6│       └── page.tsx
7└── post
8    └── [postId] // dynamic slug 
9        └── page.tsx 
10.
11.

Assuming we haven't utilized the HOC and have written our own validation logic for the auth manually. Thus, the post/[postId]/page.tsx component roughly would have looked like this:

1// post/[postId]/page.tsx
2
3interface Props extends PageProps<"/post/[postId]"> {}
4			
5export default async function PostPage({ params }: Props) {
6  const userSession = await getUserSession(); 
7  if (!userSession.ok || !userSession.data) return forbidden();
8    
9  const { session, user } = userSession.data;
10  if (!session || !user) return notFound();
11
12	const postId = (await params).postId;	
13	if(!validatePost(postId))	return notFound();
14	
15	return <Post postId={postId} />;
16}

Messy.. Especially if you have abstracted stuffs in your codebase.

Of course you can write a server function that handles all these stuff externally where it's simply being passed to each page component to do the same thing, it's also an alternative.

In this scenario, the primary goal of the HOCs would be preventing iterations over the same logic for other components wherepostIdis being consumed. It's quite overwhelming though to write the same logic.

Use it with caution: If your app doesn't scale, meaning the logic above does not repeat itself across your app components, the HOC might be an overhead rather than a solution. Assess the overall amount of required fields by checking your codebase and detecting the components that shares the same logic. Make your decision only after that for a proper React HOC replacement.

So instead, we can create a wrapper HOC function encapsulating the inner logic to not repeat ourselves by respecting the DRY principle.

Below, we have a complete HOC to handle the auth logic when working with our React components and beyond that, we're passing the props to whatever the wrapped component is.

1// src/hocs/withAuth.tsx
2import "server-only"
3
4export interface WithAuthProps {
5	session: AuthSession;
6	user: AuthUser;
7}
8
9export function withAuth<P extends object>(
10  Component: (props: P & WithAuthProps) => Promise<React.ReactNode>,
11) {
12  return async (props: P): Promise<React.ReactNode> => {
13    const res = await getUserSession();
14
15		// internal failure runtime check
16    if (!res.ok) throw new Error("Session lookup failed.");
17    
18	 	// return 403 HTTP code — new but experimental Next.js API 
19    if (!res.data) forbidden();
20    
21    const { session, user } = res.data;
22
23    if (!session || !user) forbidden(); // or notFound()
24    
25    return <Component {...props as P} session={session} user={user} />;
26  }
27}

Breaking the logic down:

1. Ensuring that we allowed proper types when we define the HOC.
   1. P extends object ensures that we only allow any kind of prop that is object otherwise warn the user back at compile time about that. Since a React component doesn't work with primitives other than object, we will be justified with the extending method of the generic type.
   2. The wrapped component's signature (props: P & Props) => Promise<React.ReactNode> forces every consumer of withAuth to declare session and user as accepted props. The typescript will automatically infer it's type at the call site which is a huge plus.
2. Don't let the auth HOC know about the resource(the part where we defined object in the type above) unless you strictly need an abstracted dedicated layer.

Takeaway: withAuthhas no business validating postId. Auth answers "is this actor allowed to make a request at all?" resource validation answers "does this specific resource exist or is it in a valid state?" Fusing them means every new component that needs auth and has its own validation rule (validatePost, validateComment, whatever comes next) forces us to either fork the HOC or bolt conditional logic onto it defeating the DRY goal we started with... We don't want that, do you want? I don't want.

In this time we simply won't pass anything and keep the rest context as-is.

1// src/hocs/withAuth.tsx
2import "server-only"
3
4export function withAuth<P extends object>(
5  Component: (props: P) => Promise<React.ReactNode>,
6) {
7  return async (props: P): Promise<React.ReactNode> => {
8    const res = await getUserSession();
9
10		// internal failure runtime check
11    if (!res.ok) throw new Error("Session lookup failed.");
12    
13	 	// return 403 HTTP code — new but experimental Next.js API 
14    if (!res.data) forbidden();
15    
16    const { session, user } = res.data;
17
18    if (!session || !user) forbidden(); // or notFound()
19    
20    return <Component {...props} />; // return the component as-is
21  }
22}

I don't think that I need to break down things like I did for the first variation and it's pretty much the same steps except passing and inferring the props of wrapped component.

Better to see how it's implemented over the components.

The most common pattern to use the HOC in our components (in my case it's a page comp.) is to define it outside of the exported component:

1// implementing the first HOC variation
2
3interface Props extends PageProps<"/post/[postId]"> {}
4
5const GuardedPost = withAuth(
6  async ({ postId, session, user }: Awaited<Props["params"]>) => 
7  	!(await validatePost(postId)) 
8  		? notFound() 
9  		: <Post postId={postId} session={session} user={user} />;
10);
11
12export default async function PostPage({ params }: Props) {
13  const { postId } = await params;
14  return <GuardedPost postId={postId} />;
15}

We could definitely move the validation logic right inside the Post component because now it looks annoying and awkward I know sorry about that 😅

Let's clean it up and assume the post component is a server component where the validatePost() does it's job inside of the <Post /> component:

1interface Props extends PageProps<"/post/[postId]"> {}
2
3const GuardedPost = withAuth(Post);
4
5export default async function PostPage({ params }: Props) {
6  const { postId } = await params;
7  return <GuardedPost postId={postId} />;
8}

We can achieve that by simply extending the post props with the HOC type that we wrote earlier:

1interface PostProps extends WithAuthProps {
2	postId: PostId,
3} 

Apparently huge difference compared to the given very first example that doesn't scale.

Now we're about the see extensive usage(one of my favorite one) of the HOCs. I told you that HOCs are highly scalable. To prove that lets add one more layer to our logic.

I guess a role based access control(RBAC) logic is a perfect candidate to append in this stuff as we're working on the posts so we're going to need to check either it's an admin or editor.

Considering the second variation of the HOC that passes nothing to the wrapper component, similarly we can create one more HOC called withRole that doesn't depend on anything:

1// src/hocs/withRole.tsx
2import "server-only"
3
4export function withRole<P extends object>(
5  Component: (props: P) => Promise<React.ReactNode>,
6) {
7  return async (props: P): Promise<React.ReactNode> => {
8    const userRole = await getUserRole();
9		
10		// every user has to have a role therefore it's an internal error
11    if (!userRole) throw new Error("User role lookup failed.");
12
13    const isGranted = await checkUserRole();
14    if (!isGranted) forbidden(); // or notFound()
15    
16    return <Component {...props} />; // return the component as-is
17  }
18}

No dependency, no undergoing props, pure component. The only point that has to be written with caution is the first returned react node type wrapped with Promise:

1Component: (props: P) => Promise<React.ReactNode>

This type represents characteristics of our wrapped function. If it's a client component therefore we can turn it into:

1Component: (props: P) => React.ReactNode

If we don't know the returned component or basically doesn't care we can create a generic type allowing the returned node to be client or server like this:

1// in types.ts
2export type ServerRenderable<P> = (props: P) => ReactNode | Promise<ReactNode>;
3
4// then in src/hocs/withRole.tsx
5
6Component: ServerRenderable<P>

The second remains unchanged nevertheless as it's belong the internal HOC component and running an async function.

Finally, the implementation of withRole inside our page component:

1interface Props extends PageProps<"/post/[postId]"> {}
2
3const GuardedPost = withAuth(withRole(Post));
4
5export default async function PostPage({ params }: Props) {
6  const { postId } = await params;
7  return <GuardedPost postId={postId} />;
8}

It's ridiculously simple to attach it into React components.

The execution order always starts from the outermost wrapper HOC and slightly moves to the right side of the line.

Speaking of the latest version of our HOC component, let's extend it with one more HOC to illustrate the communication better:

1interface Props extends PageProps<"/post/[postId]"> {}
2
3const GuardedPost = withAuth(withRole(withAnalytics(Post)));
4
5export default async function PostPage({ params }: Props) {
6  const { postId } = await params;
7  return <GuardedPost postId={postId} />;
8}

In this case, withAuth runs first, withRole second, withAnalytics third and the Post last.

The order never changes always from outermost to innermost. We could even simplify it an make it more readable by adding a composer. Like this:

1const Gated = compose(
2  withAuth,
3  withRole,
4  withAnalytics
5)(async () => {
6  // render post
7});  

An additional detail that might be worth to share with you folks is that we worked on HOCs which doesn't share anything among themselves. Each remains standalone, unaware of whatever happens on the wrapped component, only responsible to validate and return.

There's another scenario where the HOCs shares data to each other. In that case, we must remember what I have said the beginning

We always need to consider of the given and taken props.

withRole and withAuth extended only object and passed the fetched variable arbitrarily to the wrapped component. Realistically, withAuth would not have needed a prop inherintly but I can't say the same for withRole. In a real app, it should get a parameter say userId then derive something from it or use it directly in a DB function.

In this particular scenario, we have to change parameters of withRole roughly something to this:

1export function withRole<P extends object>(requiredRole: Role) {
2  return (Component: (props: P & WithAuthProps) => ReactNode | Promise<ReactNode>) => {
3    return async function RoleGuarded(props: P & WithAuthProps): Promise<ReactNode> {
4      const { userId } = props;
5      const role = await getUserRole(userId);
6
7      if (!role) throw new Error(`Role lookup failed for user: ${userId}`);
8      if (role !== requiredRole) forbidden();
9
10      return <Component {...props} />;
11    };
12  };
13}

HOCs aren't a pattern you reach for by default yet they're a pattern you arrive at, once the same auth check, role check, or tracking snippet starts showing up in one too many files. That repetition is the actual signal to look for, not "HOCs are best practice.". And folks, remember the outermost HOC always runs first. This was the The Complete Guide to Higher-Order Components in Next.js React With Typescript

Thanks for reading 👋

I got to sleep it's 4.32 PM.