<Contents>

1. [What is HOC in React?](#what-is-hoc-in-react)
2. [Practicing with a HOC in React](#practicing-with-a-hoc-in-react)
- [Writing our First HOC Wrapper for Auth](#writing-our-first-hoc-wrapper-for-auth)
- [First HOC Variation with Passing Props to the Downstream](#first-hoc-variation-with-passing-props-to-the-downstream)
- [Second HOC Variation with Passing 'Nothing'](#second-hoc-variation-with-passing-nothing)
- [HOC Implementation on our React Components](#hoc-implementation-on-our-react-components)

3. [Scaling up the HOC Implementations](#scaling-up-the-hoc-implementations)
4. [Execution Order of the HOCs](#execution-order-of-the-hocs)
5. [Interconnected React HOCs](#interconnected-react-hocs)
6. [Conclusion](#conclusion)

</Contents>

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](https://legacy.reactjs.org/docs/higher-order-components.html):
> [id=warning] 'Higher-order components are not commonly used in modern React code'  — official react dev

Now, we can only access the [legacy docs](https://legacy.reactjs.org/docs/higher-order-components.html) to view it but sadly with it's old but gold obsolete class syntax.

 [W3schools ](https://www.w3schools.com/react/react_hoc.asp)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? 

## What is HOC in React?

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.

## Practicing with a HOC in React

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.***

### Writing our First HOC Wrapper for Auth   

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:

```javascript
app/
├── layout.tsx
├── page.tsx
├── profile
│   └── [userId] // dynamic slug  
│       └── page.tsx
└── post
    └── [postId] // dynamic slug 
        └── page.tsx 
.
.
```

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:

```javascript
// post/[postId]/page.tsx

interface Props extends PageProps<"/post/[postId]"> {}
      
export default async function PostPage({ params }: Props) {
  const userSession = await getUserSession(); 
  if (!userSession.ok || !userSession.data) return forbidden();
    
  const { session, user } = userSession.data;
  if (!session || !user) return notFound();

  const postId = (await params).postId; 
  if(!validatePost(postId)) return notFound();
  
  return <Post postId={postId} />;
}
```

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* where`postId`is being consumed. It's quite overwhelming though to write the same logic. 
> [id=success] **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](https://en.wikipedia.org/wiki/Don't_repeat_yourself). 

### **First HOC Variation with Passing Props to the Downstream**

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.  

```javascript
// src/hocs/withAuth.tsx
import "server-only"

export interface WithAuthProps {
  session: AuthSession;
  user: AuthUser;
}

export function withAuth<P extends object>(
  Component: (props: P & WithAuthProps) => Promise<React.ReactNode>,
) {
  return async (props: P): Promise<React.ReactNode> => {
    const res = await getUserSession();

    // internal failure runtime check
    if (!res.ok) throw new Error("Session lookup failed.");
    
    // return 403 HTTP code — new but experimental Next.js API 
    if (!res.data) forbidden();
    
    const { session, user } = res.data;

    if (!session || !user) forbidden(); // or notFound()
    
    return <Component {...props as P} session={session} user={user} />;
  }
}
```

Breaking the logic down:	

 `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.   

The wrapped component's signature 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.

***

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**.
> [id=warning] **Takeaway:** `withAuth`has 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.

### **Second HOC Variation with Passing 'Nothing'**

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

```javascript
// src/hocs/withAuth.tsx
import "server-only"

export function withAuth<P extends object>(
  Component: (props: P) => Promise<React.ReactNode>,
) {
  return async (props: P): Promise<React.ReactNode> => {
    const res = await getUserSession();

    // internal failure runtime check
    if (!res.ok) throw new Error("Session lookup failed.");
    
    // return 403 HTTP code — new but experimental Next.js API 
    if (!res.data) forbidden();
    
    const { session, user } = res.data;

    if (!session || !user) forbidden(); // or notFound()
    
    return <Component {...props} />; // return the component as-is
  }
}
```

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.

### HOC Implementation on our React 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:**  

```typescript
// implementing the first HOC variation

interface Props extends PageProps<"/post/[postId]"> {}

const GuardedPost = withAuth(
  async ({ postId, session, user }: Awaited<Props["params"]>) => 
    !(await validatePost(postId)) 
      ? notFound() 
      : <Post postId={postId} session={session} user={user} />;
);

export default async function PostPage({ params }: Props) {
  const { postId } = await params;
  return <GuardedPost postId={postId} />;
}
```

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:

```javascript
interface Props extends PageProps<"/post/[postId]"> {}

const GuardedPost = withAuth(Post);

export default async function PostPage({ params }: Props) {
  const { postId } = await params;
  return <GuardedPost postId={postId} />;
}
```

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

```javascript
interface PostProps extends WithAuthProps {
  postId: PostId,
} 
```

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

## Scaling up the HOC Implementations

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:

```javascript
// src/hocs/withRole.tsx
import "server-only"

export function withRole<P extends object>(
  Component: (props: P) => Promise<React.ReactNode>,
) {
  return async (props: P): Promise<React.ReactNode> => {
    const userRole = await getUserRole();
    
    // every user has to have a role therefore it's an internal error
    if (!userRole) throw new Error("User role lookup failed.");

    const isGranted = await checkUserRole();
    if (!isGranted) forbidden(); // or notFound()
    
    return <Component {...props} />; // return the component as-is
  }
}
```

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`: 

```javascript
Component: (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:

```javascript
Component: (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: 

```javascript
// in types.ts
export type ServerRenderable<P> = (props: P) => ReactNode | Promise<ReactNode>;

// then in src/hocs/withRole.tsx

Component: ServerRenderable<P>
```

> [id='error'] **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:

```javascript
interface Props extends PageProps<"/post/[postId]"> {}

const GuardedPost = withAuth(withRole(Post));

export default async function PostPage({ params }: Props) {
  const { postId } = await params;
  return <GuardedPost postId={postId} />;
}
```

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

## Execution Order of the HOCs

**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:

```javascript
interface Props extends PageProps<"/post/[postId]"> {}

const GuardedPost = withAuth(withRole(withAnalytics(Post)));

export default async function PostPage({ params }: Props) {
  const { postId } = await params;
  return <GuardedPost postId={postId} />;
}
```

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

![React HOC Execution Order Diagram](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/react-hoc-execution-order-174e3421.webp)


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: 

```javascript
const Gated = compose(
  withAuth,
  withRole,
  withAnalytics
)(async () => {
  // render post
});  
```

***

## Interconnected React HOCs

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:
> [id='success']  ***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 inherently 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:

```javascript
export function withRole<P extends object>(requiredRole: Role) {
  return (Component: (props: P & WithAuthProps) => ReactNode | Promise<ReactNode>) => {
    return async function RoleGuarded(props: P & WithAuthProps): Promise<ReactNode> {
      const { userId } = props;
      const role = await getUserRole(userId);

      if (!role) throw new Error(`Role lookup failed for user: ${userId}`);
      if (role !== requiredRole) forbidden();

      return <Component {...props} />;
    };
  };
}
```

## Conclusion

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 {title} 

Thanks for reading 👋 

I got to sleep it's 4.32 PM.

In this article we're going to have a look at the HOC in practice, not only the Server-Side but also the Client-Side React patterns.

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

As developers, we experience such scenarios in our daily coding sessions, where extremely abstract and scattered **React context logics can quickly become unmanageable** when used under one provider. 
<Contents>

1. [The problem](#the-problem)
2. [How long did it take to fix?](#how-long-did-it-take-to-fix)
3. [Showcasing a Pyramid of React Context Provider](#showcasing-a-pyramid-of-react-context-provider)
4. [Getting rid of '\.provider' syntax](#getting-rid-of-provider-syntax)
5. [The 'Comment' Bottleneck of Traditional Nested React Contexts Caused by Linters and Prettifiers](#the-comment-bottleneck-of-traditional-nested-react-contexts-caused-by-linters-and-prettifiers)
6. [The Solution with Composers](#the-solution-with-composers)
- [Writing our TypeScript Types](#writing-our-typescript-types)
- [Implementing The Logic](#implementing-the-logic)

7. [Implementation on our React Components](#implementation-on-our-react-components)
8. [Bonus $Type Safe Approach$](#bonus-type-safe-approach)
9. [Conclusion](#conclusion)

</Contents>


## The problem

I was the one who dealt with a core provider logic involving five or more nested contexts mixed together. The project was pretty old and odd 🙃 but I still had to take action on the contexts. Hence, I checked the inner functionality of each, **which resulted in me wasting hours** as the inner logic concluded that the functions on the other side needed to be analyzed. 

In my case, the intention to check wasn't arbitrary though, there was race-condition between the providers and I was pretty sure that it was about the ordering. 

## How long did it take to fix?

At first, I thought to myself, "Of course it's not going to take long to figure this out", but it turned out to be "Claude, reorder the providers"..
```chart
{
  "type": "area",
  "title": "Minutes I spent over the time",
  "xKey": "context",
  "data": [
    {
      "time": 50,
      "context": "1 Context"
    },
    {
      "time": 80,
      "context": "2 Context"
    },
    {
      "time": 150,
      "context": "3 Context"
    },
    {
      "time": 225,
      "context": "5 Context"
    }
  ],
  "series": [
    {
      "dataKey": "time",
      "label": "Minutes I spent per context",
      "color": "var(--chart-3)"
    }
  ],
  "height": 320,
  "showGrid": true,
  "showLegend": true,
  "showTooltip": false
}
```

## Showcasing a Pyramid of React Context Provider

Sometimes, the providers are not designed only to be responsible with passing the props using React states. We also utilize them to derive or calculate with utility functions before passing to the context's state during the hydration or later, depending on the circumstances.

In my scenario, the provider was likely a candidate to be [Great Pyramid of Giza](https://en.wikipedia.org/wiki/Great_Pyramid_of_Giza) due to its large amount descending structure. Have a look:

```javascript
export default function StreamProvider({
  children,
  payload,
}: StreamProviderProps) {
  const worker = useWorker();
  const stream = useStream(worker, payload);

  return (
    <StreamStatusContext.Provider value={stream.status}>
      <StreamMetaContext.Provider value={stream.meta}>
        <StreamPayloadContext.Provider value={stream.payload}>
          <StreamErrorContext.Provider value={stream.error}>
            <StreamPayloadsContext.Provider value={stream.payloads}>
              {children}
            </StreamPayloadsContext.Provider>
          </StreamErrorContext.Provider>
        </StreamPayloadContext.Provider>
      </StreamMetaContext.Provider>
    </StreamStatusContext.Provider>
  );
}
```

It's a client-side wrapper, **acting as a communication channel between the worker and the main thread** for UX feedback to keep the user busy with some UI stuffs during the internal worker processes.

## Getting rid of '.provider' syntax
  
The last maintenance was carried out about a year ago, just before [React 19 ](https://react.dev/blog/2024/12/05/react-19)was introduced. So, the newer syntax, the better readability. 

**The `.Provider` part of the syntax is now obsolete and redundant**. If we trim it out then the code would look like this: 

```javascript
export default function StreamProvider({
  children,
  payload,
}: StreamProviderProps) {
  const worker = useWorker();
  const stream = useStream(worker, payload);

  return (
    <StreamStatusContext value={stream.status}>
      <StreamMetaContext value={stream.meta}>
        <StreamPayloadContext value={stream.payload}>
          <StreamErrorContext value={stream.error}>
            <StreamPayloadsContext value={stream.payloads}>
              {children}
            </StreamPayloadsContext>
          </StreamErrorContext>
        </StreamPayloadContext>
      </StreamMetaContext>
    </StreamStatusContext>
  );
} 
```

## The 'Comment' Bottleneck of Traditional Nested React Contexts Caused by Linters and Prettifiers

I believe this one may likely sound something new. When the providers are being used on the client side with bunch of nested contexts just like the one above, we usually do require comments but since we know it's internals, we're just skipping that part because, why not ✨ 

However, if you're the one working with a team, you might need to let the other developers know the purpose of the contexts unless the naming convention is clear enough or the context is pretty straightforward. **Then I assure you, the linters will be problematic.**  

No matter using **biome** or **eslint with prettier.** When you add a comment and save the file, your existing formatter may relocate the comment you made, which could cause an error, syntactically.  
 
![Illustrating shift on the React syntax when comment used ](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/context-without-composer-v1-f6cc75a9.webp)
        

***


***

There is a workaround to prevent this linter/formatter behavior when the file saved, it's ugly but at least something better:

![Relatively better approach when adding comments](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/context-without-composer-v2-54de6016.webp)




***

And here is the solution that we're about to see to all these junky formatting behaviors:

![Composer formatter effect on the same contexts ](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/context-with-composer-a3df9920.webp)


***

## The Solution with Composers

Starting with creating a new file called `composeProviders.tsx` with `.tsx` extension and place it inside your `lib` folder or wherever you think is suitable. 
> [id='warning'] The `.tsx` extension is mandatory and not arbitrary as we're working with the React components. **Don't forget to take the difference into account.**


### Writing our TypeScript Types

First, we're gonna need to create a type to **let the composer know that we're working explicitly with React components.** So our providers's type can be inferred by the composer.

```javascript
// @/lib/composeProviders.tsx
import type { ComponentType, ReactNode } from "react";

// we do not need to export since it only belongs to the composer.
type StoredProvider = ComponentType<{ value: never; children: ReactNode }>;
type RenderableProvider = ComponentType<{
  value: unknown;
  children: ReactNode;
}>;
```

The reason we used `unknown` for the type of context value is that the composer can accept any kind of value that might be controlled inside of the file where it's being passed whether via `satisfies` or `as`. I know it's less type-safe but you can use [generic types](https://burakdev.com/blogs/typescript-discriminated-unions-and-generics-complete-guide-with-examples#making-a-generic-type) to achieve 1o1 type inferring by simply converting the `Provider` type to a generic type. 

`never` is used in the tuple on purpose: `ComponentType<{ value: never }>` accepts any provider (parameter contravariance). But then we need a second, wider type for rendering.

> [id='success'] I wrote [a comprehensive deep dive in my earlier articles](https://burakdev.com/blogs/typescript-discriminated-unions-and-generics-complete-guide-with-examples#making-a-generic-type). If you feel you lack knowledge about writing generic types, I definitely recommend checking it out 🚀 


Our context type ready. Now let's design our entry point for the composer because we're gonna need to work with mapped arrays to be able to generate the composition for the React contexts.  

```javascript
// again no 'export'
type ProviderEntry = readonly [StoredProvider, unknown, string];
```

Now the `StoredProvider` indicates that we're solely allowing 3 arguments in a tuple array. `readonly` determines that we have nothing to do other than passing the undergoing array items to the subsequent action or wherever it goes. 

> [id='warning']  Consider that the `readonly` type modifier is only permitted on array and tuple literal types. So we can't use it for the `ContextProvider`


### Implementing The Logic

We're gonna need something that properly handles the order of the contexts properly as well as slightly different approach than the traditional array mapping mechanism. Unlike the traditional method, it should not use intermediate JavaScript methods with multiple maps and sorts in terms of performance and readability.

Meet with `reduceRight()`. It's viable particularly for this implementation due to it's mapping all the elements in an array, **in descending order.** 

So everything turns out to this when wrapped altogether:

```javascript
import type { ComponentType, ReactNode } from "react";

type StoredProvider = ComponentType<{ value: never; children: ReactNode }>;
type RenderableProvider = ComponentType<{
  value: unknown;
  children: ReactNode;
}>;
type ProviderEntry = readonly [StoredProvider, unknown, string];

export function composeProviders(
  providers: ProviderEntry[],
  children: ReactNode,
): ReactNode {
  return providers.reduceRight((acc, [Provider, value, key]) => {
    const P = Provider as RenderableProvider;
    return (
      <P key={key} value={value}>
        {acc}
      </P>
    );
  }, children);
}
```

Breaking down in order: 

- Takes multiple `[Provider, value, key]` entries.
- Wraps `children` with every provider **automatically**.
- Uses `reduceRight()` to **preserve** provider nesting order.
- **The first provider in the array becomes the outermost provider.**


## Implementation on our React Components

Everything we've done so far was to be able to minimize the complication of pyramid effect and nothing is harder than it's implementation. We're gonna only need to compose and get rid of the pyramid like this:

```javascript
export default function StreamProvider({
  children,
  payload,
}: StreamProviderProps) {
  const worker = useWorker();
  const stream = useStream(worker, payload);

  return composeProviders(
    [
      [StreamStatusContext, stream.status, "status"], // comment never shifts down
      [StreamMetaContext, stream.meta, "meta"],
      [StreamPayloadContext, stream.payload, "payload"],
      [StreamErrorContext, stream.error, "error"],
      [StreamPayloadsContext, stream.payloads, "payloads"],
    ],
    children,
  );
}
```


***


## Bonus (Type Safe Approach)

Remember that I mentioned earlier that we can map our types out strictly? So basically with the previous implementation, a mismatched pair compiles and fails at runtime. 

As an alternative here is a generic factory removes the cast and type checks each provider/value pair at the call site:

```javascript
import type { ComponentType, ReactNode } from "react";

type ProviderEntry = {
  readonly key: string;
  readonly render: (children: ReactNode) => ReactNode;
};

export function providerEntry<T>(
  Provider: ComponentType<{ value: T; children: ReactNode }>,
  value: T,
  key: string,
): ProviderEntry {
  return {
    key,
    render: (children) => (
      <Provider key={key} value={value}>
        {children}
      </Provider>
    ),
  };
}

export function composeProviders(
  providers: readonly ProviderEntry[],
  children: ReactNode,
): ReactNode {
  return providers.reduceRight((acc, { render }) => render(acc), children);
}
```

Implementation fairly longer but better:

```javascript
export default function StreamProvider({
  children,
  payload,
}: StreamProviderProps) {
  const worker = useWorker();
  const stream = useStream(worker, payload);

  return composeProviders(
    [
      providerEntry(StreamStatusContext, stream.status, "status"),
      providerEntry(StreamMetaContext, stream.meta, "meta"),
      providerEntry(StreamPayloadContext, stream.payload, "payload"),
      providerEntry(StreamErrorContext, stream.error, "error"),
      providerEntry(StreamPayloadsContext, stream.payloads, "payloads"),
    ],
    children,
  );
}
```
   
 Now, in order to test it out, as instance let's deliberately mistaken the passed state using the `stream.status` for `StreamMetaContext` like this:

```javascript
providerEntry(StreamMetaContext, stream.status, "meta"),
```


yields a type error at compile time:

```javascript
Argument of type 'StreamStatus | null | undefined' is not assignable to parameter of type 'unique symbol | StreamMeta | null | undefined'.
  Type '"COMPLETED"' is not assignable to type 'unique symbol | StreamMeta | null | undefined'.
```

The error in the IDE looks like this:

![Typescript Compile Issue in the Visual Studio](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-01-021132-f83ee888.webp)

Ultimately,  it's much safer and solid path to go with in prod-grade apps without concerning about runtime/compile issues.

## Conclusion

The takeaways already given above so It appears to me that there is no more saying to be added below here😀. Of course you can utilize state managers like Redux or Zustand for smaller implementations depending on the use case and not tangle with any of this but if you think it's an overhead and willing to stay native to React, here is the solution for all that spaghetti or pyramid context chains. 

Thanks for reading. 

It's again a late night, 02:27 AM.

Practicing with the type-safe reusable composers to organize the existing pyramid-like React context providers into something readable

Preventing The React Context From Turning Into Pyramids with Typesafe Composer

<Contents>

1. [Most Apps Require Debouncing](#most-apps-require-debouncing)
2. [Worst Scenario Without Debouncing](#worst-scenario-without-debouncing)
3. [Debouncing Implementation Without React](#debouncing-implementation-without-react)
- [What Is Debouncing?](#what-is-debouncing)
- [Why Debouncing and Why Not Throttling?](#why-debouncing-and-why-not-throttling)
- [Implementation](#implementation)

4. [Debouncing with React and TypeScript](#debouncing-with-react-and-typescript)
- [Implementation](#implementation-1)
- [Using It in Our Search Component](#using-it-in-our-search-component)

5. [Conclusion](#conclusion)

</Contents>

We mostly do **require limitations based on the user's activity** when building our front-end to prevent excessive API calls on the server-side that may ~~bloat the network waterfall~~ and eventually slows down both — the front and backend 

The same applies for the client-side events that we don't anticipate to occur in prod when building an app. 

To simulate the bottleneck, I have created an imaginary app for a "first-time" customer. We will address this issue implicitly throughout the article with a little bit of improvision ofc. 

|                            Category                            |                            E-commerce                            |
| --- | --- |
|                            Tech                            |                           React, Next.js                            |
|                            Target                            |                           User searching a book for his kid                             |
|                            Impacts                            |                           A direct impact to the URI via query params                             |
|                            Psychology of The User                            |                           Hardcore — In rush, impatient and undecided                            |

## Most of the Apps Require Debouncing 

Imagine an impatient user who is undecided and looking for something. They mess around with your search bar, which then becomes unresponsiv**e due to the excessive number of API calls**, because your client-side search bar was designed solely to change the query parameters.


Say we have a React `useState` which internally being used inside our custom hook that triggers on each keystroke. An effect runs — externally somewhere else — sending a `fetch` request to the API to sync with the user query inside URI's query param.

|                          Route URL                          |                          `example-ecommerce.com/discover?q=`                          |
| --- | --- |
|                          1st attempt                          |                          `?q=bo`                          |
|                          2nd attempt                          |                          `..?q=boo`                          |
|                          3rd attempt                          |                          `..?q=boot`                          |
|                          4th attempt                          |                          `..?q=boo`                          |
|                          ...10 more attempts                          |                          —                          |
|                          16th attempt                          |                          `..?q=book%20%for%20%kid`                          |
|                          17th attempt                          |                          `?q=book%20%for%20%kids`                          |

When it comes to an app welcoming 1K+ MAU users, **the impact would be pretty disruptive without debounce on the server**. Assuming 300ms debounce, HTTP/2, about 200ms between keystrokes. So the **Response time per attempt (ms)** likelihood would have been illustrated as shown below.

<center>Response time per attempt (ms): 17 fired vs 3 fired</center>
```chart
{
  "type": "bar",
  "title": "Response time per attempt (ms): 17 fired vs 3 fired",
  "xKey": "attempt",
  "data": [
    {
      "attempt": "#1",
      "no_debounce": 142,
      "debounced": 0
    },
    {
      "attempt": "#2",
      "no_debounce": 168,
      "debounced": 0
    },
    {
      "attempt": "#3",
      "no_debounce": 155,
      "debounced": 0
    },
    {
      "attempt": "#4",
      "no_debounce": 171,
      "debounced": 0
    },
    {
      "attempt": "#5",
      "no_debounce": 203,
      "debounced": 164
    },
    {
      "attempt": "#6",
      "no_debounce": 196,
      "debounced": 0
    },
    {
      "attempt": "#7",
      "no_debounce": 241,
      "debounced": 0
    },
    {
      "attempt": "#8",
      "no_debounce": 258,
      "debounced": 0
    },
    {
      "attempt": "#9",
      "no_debounce": 287,
      "debounced": 171
    },
    {
      "attempt": "#10",
      "no_debounce": 274,
      "debounced": 0
    },
    {
      "attempt": "#11",
      "no_debounce": 331,
      "debounced": 0
    },
    {
      "attempt": "#12",
      "no_debounce": 349,
      "debounced": 0
    },
    {
      "attempt": "#13",
      "no_debounce": 378,
      "debounced": 0
    },
    {
      "attempt": "#14",
      "no_debounce": 362,
      "debounced": 0
    },
    {
      "attempt": "#15",
      "no_debounce": 412,
      "debounced": 0
    },
    {
      "attempt": "#16",
      "no_debounce": 436,
      "debounced": 0
    },
    {
      "attempt": "#17",
      "no_debounce": 455,
      "debounced": 158
    }
  ],
  "series": [
    {
      "dataKey": "no_debounce",
      "label": "No debounce",
      "color": "var(--chart-1)"
    },
    {
      "dataKey": "debounced",
      "label": "Debounced (300 ms)",
      "color": "var(--chart-2)"
    }
  ],
  "height": 320,
  "showGrid": true,
  "showLegend": true,
  "showTooltip": true
}
```

***

## Worst Scenario without debouncing

Let's picture our imaginary search component in React that listens the input changes in a way that it eventually syncs with the query strings via `useSearchParams()`  

```typescript
import { useSearchParams } from "@/hooks/useSearchParams";
import { type ChangeEvent, useEffect, useState } from "react";

export function Search() {
  const [params, setParams] = useSearchParams();

  function handleChange(e: ChangeEvent<HTMLInputElement>) {
    setParams(e.target.value);
  }

  useEffect(() => {
    /* 
    	cleanup on next hydration 
    	recommending to place it inside useSearchParams()   
    	not here as it's illustration only
    */
    return () => setParams("") 
  }, [params]);

  return (
    <>
      <label htmlFor="search">Search</label>
      <input value={params} onChange={handleChange} id="search" />
    </>
  );
}
```

> [id='success'] If we want the app to be scalable, **we better not compromise on the distribution while striving to keep the semantics**. In short, one giant `<SearchBar />` is always ugly and sluggish pattern *compared to partially designed component system that scales*. 


Yes, it would be much easier for me to implement an aggregated component without using any query params, replacing them with a server action that submits the internal state without manipulating even touching the query params. 

At least then I could have managed everything in one giant file, *but the system itself would have been prone to errors caused by even the slightest detail being overlooked*, something being forgotten while I was taking a sip of coffee and thinking about what to prepare for dinner, who knows...


## Debouncing Implementation Without React

### What is Debouncing?

[**Debouncing**](https://developer.mozilla.org/en-US/docs/Glossary/Debounce), in the context of programming, means to discard operations **that occur too close together** during a specific interval, and consolidate them into a single invocation.

That's fairly enough to become one of the most important pattern to be eager at through the front-end engineering. **Our undecided guy as alone may not indicate a bottleneck but many of them do**. To prevent such behaviors like overloading the server that we address in this article, we must implement.  

### Why Debouncing and Why Not Throttling?

It always depends on the outbound thing that you're working on. **If the type were a function  rather then a value, throttling would be better pattern to go with**. The throttle is designed to apply a rate limit to function execution, by design. 

![Debounce vs Throttle in Real World — AI generated](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/debounce-vs-throttle-3b3e506b.webp)

As you can see, debounce is highly dependent to other conditions like the keystroke speed or pause rate of the user while throttle is simply, not.

### Implementation

A simple Debounce function in JavaScript:

```javascript
function debounce(fn, t) {
  let timeoutId;

  return function(...args) {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(fn.bind(this, ...args), t)
  }
}
```

When the returned (Debounced) function is called, *it clears any previously set timeout and sets a new timeout to execute the callback function* after a delay of `t` milliseconds. 

Therefore, the number of keystrokes while searching decreases dramatically.

Enriching this function with TS:

```typescript
function debounce<T extends (this: any, ...args: any[]) => any>(
  fn: T,
  t: number,
): (this: ThisParameterType<T>, ...args: Parameters<T>) => void {
  let timeoutId: ReturnType<typeof setTimeout> | undefined;

  return function (this: ThisParameterType<T>, ...args: Parameters<T>) {
    if (timeoutId !== undefined) clearTimeout(timeoutId);

    timeoutId = setTimeout(() => fn.apply(this, args), t);
  };
}    
```

If you do work solely on Node, you can also use `NodeJS.Timeout` instead of `ReturnType<typeof setTimeout>`.
> [id='info'] I wont get into the weeds of type inferring and other implementation practices in this article, I have already addressed comprehensively [in my other articles](https://burakdev.com/blogs). If you're struggling to understand the context of what's written above, you can check those out.  

## Debouncing with React and Typescript

It's way far simpler than the one above thanks to the lovely `useState()`. No need to deal with binding or applying things which makes our work easier. 

### Implementation

So, we're going to need a reusable custom hook where we can put wherever we want to make values debouncy. Let's call it `useDebouncedValue` or you can go straight with `useDebounce` as you wish. 

We will utilize 2 things and wrap everything around them:
- `useEffect`
- `useState`

Btw if you have better naming convention, put it in the comments 😄 

```typescript
// @/hooks/use-debounced-value.ts

"use client";

import { useEffect, useState } from "react";

type UseDebounce = <T>(value: T, delay: number) => T;

export const useDebouncedValue: UseDebounce = (value, delay) => {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const debounce = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(debounce);
  }, [value, delay]);

  return debouncedValue;
};
```

Or,

```javascript
"use client";

import { useEffect, useState } from "react";

export const useDebouncedValue = <T>(value: T, delay: number): T => {
  const [debouncedValue, setDebouncedValue] = useState<T>(value);

  useEffect(() => {
    const debounce = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(debounce);
  }, [value, delay]);

  return debouncedValue;
};
```

A generic type at the top is all we need, allowing us to infer the type automatically **without needing to narrow it down** from the component where our hook is being called . 

> [id='warning'] **TypeScript Caveat**: It's dead serious important to mention that the generic type inferring is the best fit here, otherwise you could struggle with determining   isolated type granted only for the state. Definitely an anti-pattern like `useState<string | number>(value)`


***


### Using it in Our Search Component

The only action that can be associated with the custom hook we created is the query value. So spotting it in our very first React component and implementing the hook around it would have looked like this,

```typescript
"use client";

import { useDebouncedValue } from "@/hooks/use-debounced-value";
import { useSearchParams } from "@/hooks/useSearchParams";
import { type ChangeEvent, useEffect, useState } from "react";

export function Search() {
  const [params, setParams] = useSearchParams();
  const [value, setValue] = useState<string>(params);
  const debouncedValue = useDebouncedValue<string>(value, 300);

  useEffect(() => {
    setParams(debouncedValue);
  }, [debouncedValue, setParams]);

  function handleChange(e: ChangeEvent<HTMLInputElement>) {
    setValue(e.target.value);
  }

  return (
    <>
      <label htmlFor="search">Search</label>
      <input id="search" value={value} onChange={handleChange} />
    </>
  );
}
```

> [id='error']  Since we haven't given a word to the `useSearchParams` I had to use the effect inside the `<Search />` component. However please consider that it's not an ideal pattern to go with. Instead, we should have used it inside the existing effect of `useSearchParams` hook not where it's called. What we did is nothing but adding overhead. 
 

## Conclusion

Our undecided shopper is not an edge case. He is the default user, and every keystroke he makes is an event your app has to survive. Without a limit, 17 keystrokes became 17 requests, and the cost multiplies with every other user doing the same thing. With a 300ms debounce, the same session fires 3.


***

<center>Waterfall impact summary</center>
```chart
{
  "type": "area",
  "title": "Waterfall impact summary",
  "xKey": "metric",
  "data": [
    {
      "metric": "Requests fired",
      "no_debounce": 17,
      "debounced": 3
    },
    {
      "metric": "Peak in-flight",
      "no_debounce": 3,
      "debounced": 1
    },
    {
      "metric": "Wasted responses",
      "no_debounce": 16,
      "debounced": 2
    },
    {
      "metric": "Out-of-order risk",
      "no_debounce": 6,
      "debounced": 0
    }
  ],
  "series": [
    {
      "dataKey": "no_debounce",
      "label": "No debounce",
      "color": "var(--chart-1)"
    },
    {
      "dataKey": "debounced",
      "label": "Debounced (300 ms)",
      "color": "var(--chart-2)"
    }
  ],
  "height": 320,
  "showGrid": false,
  "showLegend": true,
  "showTooltip": true
}
```
***

**The fix is small**. One generic hook, `useDebouncedValue`, sits between the input and the URL:
- The input **binds to local state**, so typing stays instant.
- The debounced value is the only thing allowed to touch the query params and trigger a fetch.
- The server sees the user’s intent, not the hesitation.

Thanks for reading 🖖

Debouncing helps prevent excessive API requests caused by rapid user input. Learn how to implement a reusable, type-safe debounce TypeScript util in React.

An Undecided User Might Be Killing Your Server All Along

<Contents>

1. [The Goal](#the-goal)
2. [Preparatory Work](#preparatory-work)
3. [Measuring Bundle Size of Candidates](#measuring-bundle-size-of-candidates)
- [Shiki](#shiki)
- [Existing One](#existing-one)
- [Why Bundle Size Matters Less in My Case](#why-bundle-size-is-less-matter-in-my-case)
- [Setting Up Next\.js Turbopack Bundle Analyzer](#setting-up-nextjs-turbopack-bundle-analyzer)

4. [Inspecting the Bundled Map](#inspecting-the-bundled-map)
5. [Breaking Down the Analyzer UI](#breaking-down-the-analyzer-ui)
6. [Measuring the Current Highlighter Library](#measuring-current-highlighter-library)
7. [Switching Between Libraries $Before \& After$](#switching-between-libraries-before-after)
8. [Summary](#summary)

</Contents>


Today, I am going to do something I have never done before. **This article will be updated as I work to replace the existing syntax highlighter library on this site with a newer one**. 

I've done this benchmarking-like staffs in my side projects as well as at work, so I'm pretty confident in it.

## The Goal

Basically, think of this *as a live journal.* I won't use AI at any point during this process, so I can only explain things based on the goal.

Throughout the process, **I will share timestamps so you can measure** how long it takes to analyze something that is already in production from scratch.

## Preparatory Work
> [id='info'] Thursday, October 29, 2026 (UTC+1) 2:35 PM

So at first, take a look at what I'm replacing and why.

I've been all the time rendering the code snippets in my articles using `next-mdx-remote-client` which is a [wrapper](https://github.com/ipikuka/next-mdx-remote-client) of **`@mdx-js/mdx`** for **`nextjs`** apps in order to load MDX content alongside the essential supplements `rehype-slug` and `remark-gfm`.

The reason I want to move something extensive is **limited support on tokenization and capabilities** of what `next-mdx-remote-client` provides.

That's why I choose [shiki](https://shiki.style/) as a better alternative because:

- It's actively maintaining
- Extensive and modular design
- Better [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) support
- Works async on demand
- It just cooler 😄

I've tested and used, works very well regardless so..

## Measuring Bundle Size of Candidates 
> [id='info']  3:02 PM

I am going to go [bundlephobia](https://bundlephobia.com/) for this one and put some table down here to see what's being added at the top of app's bundle. 

### Shiki
 
|              Modules              |              Size (minified + gzipped)              |
| --- | --- |
|              `@shikijs/core`              |              34.7 kB              |
|              `@shikijs/engine-javascript`              |              19.9 kB              |
|              `@shikijs/langs`              |              1.4 kB              |
|              Total              |              \~56 kB               |

### Existing one

|             Modules             |             Size              |
| --- | --- |
|             `prism-react-renderer`             |             25.6 kB             |

### Why Bundle Size is Less Matter in My Case

Apparently, Shiki is doubling the size of the bundle. Despite knowing this, why would I want to implement something heavier? Am I stupid or smth?

Speaking of which — no, I am not. 

No need to overlook and assess *solely based on the bundle size* when replacing a front-end feature because there are other factors to be considered.

The **bundle size** is extremely **important for above the fold elements** such as banner images in the hero section or anything else located where users first interact. These elements significantly impact core web vitals.

In my article scenario, the code snippets are always rendered below the fold, so speed is not a priority.

So why I do need to compare bundle sizes then? 

Well, fair question. We will come there soon.       

### Setting up Next.js Turbopack Bundle Analyzer
> [id='info'] 3:33 PM

In order to compare the current bundle distribution with the updated version later on, I need to analyze it. So, let me open things up and address how to replicate it.

Okay, in my case, I use Next.js 16.3.8 with the Pages Router. I statically export everything because I don't have anything that requires runtime agnostics. This maximizes the SEO advantage since it's a static personal blog project.
> [id='warning'] The reason that I haven't bump the repo up to v16.4 is that the vercel team encountered couple of major issues with the pages router impacted the dev server which crushes the app entirely out of nowhere.

My `next.config.ts` is like this:

```javascript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  images: {
    unoptimized: true,
    remotePatterns: [
     /* patterns.. */
    ],
  },
  reactStrictMode: true,
  devIndicators: false,
  reactCompiler: true,
  experimental: {
    useTypeScriptCli: true,
    turbopackRustReactCompiler: true,
  },
  allowedDevOrigins: ["***"],
};

export default nextConfig;
```

Then to be able to utilize bundle analyzer, so I added this line under `scripts` inside `package.json`

```javascript
"scripts": {
    "dev": "next dev -p 49826",
    "build": "next build",
    "analyze": "cross-env ANALYZE=true next build && npx next analyze",
    ...
}
```

Then run: 

```javascript
npm run analyze 
```

This will pop up a site:

```javascript
✓ Running next.config.ts took 45ms
   Analyzing a production build...
✓ Analyze completed in 8.6s.
   Bundle analyzer available at http://localhost:4000
```

> [id='warning'] The path slightly changes when using webpack instead of turbopack. I am currently using turbopack so I don't need to install [this plugin](https://nextjs.org/docs/pages/guides/package-bundling#nextbundle-analyzer-for-webpack) called `@next/bundle-analyzer` . If you use webpack, you should wrap the next config file around this plugin.


## Inspecting The Bundled Map 

> [id='info'] 4:46 PM (I had a break 🙂)

At first glance, the tree map looks like this 😱

![Next.js treemap view](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-164927-9451f136.webp)

We are currently viewing the dynamic slug `/blogs/[slug]` page which statically generated with `getStaticProps` as it's shown at the top left corner and I am able to switch between the pages. At the right side we can see the size of resolved modules grouped by it's type.
  
## Breaking Down the Analyzer UI

If I zoom in,

![Right top corner settings — zoomed in](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-172025-f7216c38.webp)

I've marked each part to clarify their role in this:

1. Switching between the views, there are 2 modes on that; treemap which we see above and the table map and when switched, it looks like this:

![analyzer table view](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-172547-e9664282.webp)

I can sort things out and identify the modules that take up the most space. Each list item is collapsible, and you can open them up to inspect them. It's pretty useful, and I'll be using this view soon, too. 

2. Again a filter feature to sort out the modules only used on the server/client side. The trick is that when the filter set to client, **you're never going to see a pure client component** marked as `client` unless its and asset like the css or font files. Instead, alongside of the client mark, you're always gonna see `server` mark, **because the client components inherently are server components by default**([see RSC](https://nextjs.org/docs/app/getting-started/server-and-client-components#how-do-server-and-client-components-work-in-nextjs)). You can probably and only see assets marked as client.
3. Enabling us to filter by the file types: JS, CSS, JSON and Asset options are available.       
4. It's a switcher that tracks and displays only modules with an initial synchronous path. In other words, this is where the optimization shines. When enabled, fewer shipped modules can be measured due to lazy loading optimizations, which defer the application of modules until they are needed, rather than initially. 
5. This shows the total size of the module. **The compressed version estimates the number of bytes needed to download the bundle, while the uncompressed version helps identify the modules that contribute to the bundle's size**. The compressed size is primarily used for *transfer costs*, while the uncompressed size is a *diagnostic metric.* 

Lastly, let's move to the top right side of the site. 


![top right corner of bundle analyzer UI](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-180502-6ef056a5.webp)


This part is completely related with the auto generated folder by Next.js called `.next`

Each time you build your project, it is exported with an ID, which allows me to switch between builds. The selection component marked as "1" opens the pop-up. As its name implies, the second selection marked as "2" allows me to switch between tabs to compare builds and see how they impact the project. Recently, to clean things up, I removed the `.next` folder, which also deleted the old build. However, you will still be able to switch between builds as long as you keep your `.next` folder.         

> [id='success'] I found that it's also fetching the Git commits and tidying them up. It turns out that they're easily trackable builds, which is a good thing.

![page route section UI](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-185149-a16fa06e.webp)

1. Static and dynamic pages are found in the app. If a page is marked with a slug, then I can understand that it has multiple variations of the same schema.
2. It includes the generated artifacts by Next.js. This differs from the compressed module size because the artifacts belong to the app itself, not its dependencies. Regarding the dynamic slug, statically generated blog posts are rendered in our file exactly as seen here. 

```javascript
blogs
├── an-undecided-user-might-be-killing-your-server-all-along.json
├── i-have-built-an-ultimate-blogging-workspace-and-open-sourced-it.json
├── is-react-tanstack-query-too-biased-deep-dive-real-life-data-fetching-practices-chapter-1.json
├── preventing-the-react-context-from-turning-into-pyramids-with-typesafe-composer.json
├── the-complete-guide-to-higher-order-components-in-next-js-react-with-typescript.json
└── typescript-discriminated-unions-and-generics-complete-guide-with-examples.json
```

Because we're using `getStaticProps` on that page telling Next to build it's artifacts which results in JSON files. 

For those who might be curious, the file starts and ends like this: 

```javascript
{
  "pageProps": {
    "meta": {
      "id": 16,
      "title": "An Undecided User Might Be Killing Your Server All Along",
      "tags": [
        "react",
        "typescript",
        "javascript"
      ],
      "published_at": "2026-10-12T21:06:38.698+00:00",
      "description": "Debouncing helps prevent excessive API requests caused by rapid user input. Learn how to implement a reusable, type-safe debounce TypeScript util in React.",
      "banner_image": "https://***t-debounce-banner-0fc789bb.webp",
      "level": 1
    },
    .
    .
 },
 "__N_SSG": true
}
```
 
Each one contains the full data of an article. The analyzer shows the total page size under the hood. To verify this, take a look at the folder containing the generated file routed inside `.next/static/blogs/*`.  

![generated blog post sizes](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-191128-46fd3bc3.webp)


## Measuring Current Highlighter Library

> [id='info'] 6:45 PM

My target is `prism-react-renderer` and everything around it, so I searched for it in the search bar. After that, I got a highlighter module like this one.

![prism-react-renderer with initial load only treemap view](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-191755-62f49b79.webp)

**50.14 kB.** As I told you, my goal isn't to reduce the bundle size. It's ensuring that a better alternative doesn't blow up through the app.

I'm switching to Table View to see how the module is passed to its target.

![prism-react-renderer in table view import chain](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-29-192219-3c2a3876.webp)
 
I'll note the measurements here for initial load only mode.

- **50.14 KB** compressed (estimated)
- **165.61 KB** uncompressed
- Initial vs. without, **0kB** diff.

Now it's time for me to implement Shiki.

## Switching Between Libraries (Before After)

> [id='info'] 7:45 PM

I've done implementation. The time it takes to open an article is noticeably faster. For those who are curious, I used a promise-based singleton with the JavaScript Regex Engine instead of the default Oniguruma Engine [to render tokens](https://shiki.style/guide/regex-engines#regexp-engines).  I don't know what I've been using so far with `next-mdx-remote-client`

I added the following optimizations to the highlighter component:

- Module-based lazy loading with `dynamic` export.
- Singleton pattern to ensure instantiation doesn't repeat twice.
- Removing `pre` mdx component from barrel export.
- Eliminating internal re-render issues.

The results are surprising because, even though I switched to something more extensive, I measured a reduction in size. 🎊

|    Initial Load     |    Compressed    |    Uncompressed    |    Diff    |
| --- | --- | --- | --- |
|    Shiki (new)    |    46.76 KB    |    146.54 KB    | - *3.38 KB*    |
|    next-mdx-remote-client (old)    |    50.14 KB    |    165.61 KB    | + *3.38 KB*    |

***

The diff in the next analyzer treemap view is visibly changed as well,

![next bundle analyzer treemap view diff](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/treemap-view-bundler-comparison-d03282ef.webp)


You're probably seeing the updated version of the syntax highlighter in this article now, but if we show you a before-and-after comparison, it would look like this:

![comparison of the highlighter UI](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/syntax-diff-before-after-05eac607.webp)

Keep in mind that these measurements only apply to the initial load, which differs dramatically in size. In the context of my goal, this is an achievement. However, if your goal is to reduce the overall bundle size, then it is not an achievement.

Lastly, I checked the Compare Builds tab to show you the actual difference.

![comparing builds after shiki added](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-10-30-195245-a7423007.webp)

**+99.48 KB** may seem like an overhead to you, but it's actually a better version of what you see marked in yellow. What matters ever is that it's lighter on the initial load depending on the goal we put in this article. 

## Summary 

> [id='info'] 8:15 PM — everything took five hours, including writing the article, performing all the optimizations, and crafting these materials to help you illustrate things better. I think it's fair. 🙂

Replacing a front-end library isn't always about reducing bundle size, it's about understanding its impact on the application and making informed trade-offs. 

In this live experiment, I replaced the existing syntax highlighting solution with Shiki, configured lazy loading and did optimization staffs, ultimately reducing the initial compressed bundle size by 3.38 KB despite switching to a more extensive library. 

You can inspect the implementations and shiki components using the links given below,

- [shiki.ts](https://github.com/Masculinn/burakdev/blob/main/src/lib/shiki.ts)
- [md-pre.tsx](https://github.com/Masculinn/burakdev/blob/main/src/components/blogs/ui/md-pre.tsx)
- [highlight-code-snippet.tsx](https://github.com/Masculinn/burakdev/blob/main/src/components/blogs/highlight-code-snippet.tsx)

Thanks for reading.

A live, data-driven analysis of how replacing a library affects a Next.js production bundle, tracking the difference in bundle size.

Live Next.js Bundle Analysis: Measuring the Impact of Replacing a Syntax Highlighting Library

The hidden gem behind the React query is revealed. Take a gigantic dive into the traditional ways of data fetching vs newfangled ways where the term "query" is mentioned. 

Is React(tanstack) Query Too Biased? Deep dive: Real Life Data Fetching Practices — Chapter 1

Master advanced TypeScript patterns: Learn discriminated unions for precise type narrowing and generic types for building scalable, type-safe systems with practical RBAC examples and custom utility implementations.

TypeScript Discriminated Unions and Generics: Complete Guide with Examples

I always thought that using our own custom solutions over the ready ones is not necessary but genuine idea because we face with an unknown in other words **real challenge.** I used to write my articles using [Obsidian](https://obsidian.md/) and manually update the DB so far.  

It turns out actively using this app to write and manage my technical articles. Just like this one 😅

Check out the [Github repo](https://github.com/Masculinn/blog-editor) for the source code. 

<Contents>

1. [Introduction](#introduction)
2. [Motivation](#motivation)
3. [Architecture](#architecture)
4. [Installation](#installation)
- [1\. Requirements](#1-requirements)
- [2\. Database Configuration](#2-database-configuration)
- [3\. Environment Configuration](#3-environment-configuration)
- [4\. Database Types](#4-database-types)
- [5\. Running the App](#5-running-the-app)

5. [Tidy Up The Repo — important](#tidy-up-the-repo--important)
6. [Usage \& Writing Your First Article](#usage--writing-your-first-article)
- [Important Note for Unix\-Based OS Developers](#important-note-for-unix-based-os-developers)
- [Command Center \& Shortcuts](#command-center--shortcuts)

7. [Contributing](#contributing)
8. [Acknowledgements](#acknowledgements)

</Contents>

## Introduction 

The **open-source Ultimate Blog Editor App** brings together the Markdown editing experience of [Obsidian](https://obsidian.md/) and the publishing flexibility of [Substack](https://substack.com/) in a single workspace.

*The stack doesn't cost a penny.* [*Supabase* ](https://supabase.com/)*and* [*Netlify*](https://www.netlify.com/) *free plans are suitable. It won't let you down halfway through even at scale.* 

That said, it comes with amazing features listed down below:
 
- **Rich-Text Editing**
- **Blazing Fast Editing**
- **Markdown Editing Mode**
- **MDX Content Viewer**
- **Dynamic Error Display for Compiled MDX Source** 
- **Media Library** 
- **Image Optimization (converting primary formats to `.webp`)**
- **Extensive Autocomplete In English** 
- **Custom Content Components (including charts from `recharts`)**
- **Command Center**
- **50+ Predefined Eye Soothing Backgrounds**
- **Draft & Post Management**
- **Document Serialization and Compression**
- **URL-Based Document State**
- **Comprehensive Keyboard Shortcuts With Full Accessibility Support**
- **Dialogs, Sheets, Shared Controls**
- **Feedback and Cloud Syncing**
- **Backend Integration**

**This project is primarily tailored for my personal use**, but it is also intended to serve as a reference for others interested in the editor architecture and development of editor features. It's so easy to change the serialized custom components and allowing you to curate them as you wish. 

![App features collection](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/blog-editor-thumb-98412b75.webp)


***


It serve as a starting point for building custom editor apps with its highly modular architecture and extensibility. Just like a puzzle box, it can be customized to fit your needs.

|      tech      |      version      |
| --- | --- |
|      Next.js      |      ≥16      |
|      React / React DOM      |      >19      |
|      TypeScript      |      ≥5.0      |
|      Lexical      |      ≥0.49.0      |
|      Supabase JS      |      ≥2.112.3      |
|      Tailwind CSS      |      ≥4.0.0      |
|      shadcn      |      ≥4.19.0      |
|      Base UI      |      ≥1.7.0      |
|      next-mdx-remote-client      |      ≥2.1.12      |
|      React Hook Form      |      ≥7.87.0      |
|      Zod      |      ≥4.5.4      |


## Motivation

Of course, those who rely on others' solutions rather than coming up with their own in 2026 are not fools or timid. What I mean is that whatever [Substack](https://substack.com/) or [Obsidian](https://obsidian.md/) provides is maybe convenient enough for you.  

Therefore you might not end up with going further, it's totally up to you. 

*As far as I am concerned, these techs don't meet my expectations on their own, but would meet them if they were combined, if you're the one looking from the same window like me then you've come to the right place.*


## Architecture

The app follows a modular architecture that separates editing, document previews, and content management into dedicated feature areas. Shared UI components, an extensible Lexical editor, and centralized server actions keep the code organized and make it easier to maintain and expand. Respected to DRY principles heavily.

- **Admin entry point(mainland):** `app/(admin)/admin/page.tsx` provides the admin route, with access-control logic organized in `proxy.ts` and `lib/auth.ts`.
- **Feature modules:** `features/` separates the editor, document viewer, and management tools for drafts, posts, and the media library.
- **Extensible editor:** `components/editor/` organizes Lexical nodes, plugins, extensions, toolbars, and Markdown transformers. Charts and Contents have dedicated modules for editing, rendering, and conversion.
- **MDX rendering:** `components/mdx/` defines content components and processing plugins, while `lib/mdx/` handles serialization and related error handling.
- **Server and DB layer:** `app/actions/` groups content operations, supported by the server database client in `lib/db/` and generated database types in `types/`.
- **State and validation:** `store/document.store.ts` holds document state, `providers/tools-provider.tsx` supplies shared tool context, and `schema/` defines draft validation.
- **Shared interface:** `components/ui/`, reusable modals, and `hooks/` provide consistent controls, dialogs, keyboard shortcuts, and URL parameter handling.

The working tree is pretty straightforward and scalable with it's modular design: 

```javascript
src/
├── app/
│   ├── (admin)/admin/    # Entry point
│   └── actions/         # Server-side content operations
├── features/
│   ├── editor/          # Editor workspace
│   ├── document-viewer/ # Content preview
│   └── tools/           # Drafts, posts, and media management
├── components/
│   ├── editor/          # Lexical nodes, plugins, and extensions
│   ├── mdx/             # MDX rendering components
│   └── ui/              # Shared interface components
├── lib/                 # Auth, database, and serialization
├── store/               # Document state
├── providers/           # Shared tool context
├── hooks/               # Reusable React hooks
├── hoc/                 # Content and metadata wrappers
├── schema/              # Validation schemas
├── types/               # Application and database types
├── constants/           # Tool and editor configuration
├── utils/               # Supporting utilities
└── proxy.ts             # Request interception  
```

## Installation

### 1. Requirements

You will need:
- Node.js >= 22
- npm

Clone the repository:
```javascript
git clone https://github.com/Masculinn/blog-editor.git
cd blog-editor
```

Install dependencies:
```javascript
npm install
```

> [id=warning] **⚠️ CAUTION: Before continuing further you must configure the DB layer. Do not attempt running the dev server unless all the database environments and tables are configured properly. See instructions below to be able to start the dev server.**     


***

### 2. Database Configuration

Visit [Supabase auth page ](https://supabase.com/dashboard/sign-up)to signup or if you have already an account simply login. Create a new organization and choose your own namespace. After that, create a table called 
`blog_posts` and paste the given [PostgreSQL ](https://www.postgresql.org/)snippet below into the SQL Editor section placed in the sidebar of your dashboard.   
 
This will create our very first table for our articles.

```javascript
create table public.blog_posts (
  id serial not null,
  title text not null default 'title'::text,
  content text not null,
  tags text[] not null,
  published_at timestamp with time zone null default now(),
  description text not null default 'I AM JOHN DOE BUT CANT PROVE IT'::text,
  banner_image text not null default 'MY_DEFAULT_IMAGE_URL'::text,
  level numeric not null default '1'::numeric,
  constraint blog_posts_pkey primary key (id),
  constraint blog_posts_level_check check ((level > (0)::numeric))
) TABLESPACE pg_default;
```

> After configuring the DB and ensuring everything is stable, you can curate the predefined tables however you want. 

Next, we need the secondary table for our article candidates that isn't actually ready to be considered under the category of posts. I call it **draft.** 

Paste the given snippet below to create **draft** table into the SQL Editor as well.

```javascript
create table public.drafts (
  id serial not null,
  title text not null default 'title'::text,
  content text null default 'The quick brown fox jumps over the lazy dog.'::text,
  tags text[] null,
  published_at timestamp with time zone null default now(),
  description text null,
  banner_image text null,
  level numeric not null default '1'::numeric,
  constraint drafts_pkey primary key (id),
  constraint drafts_level_check check ((level > (0)::numeric))
) TABLESPACE pg_default;
```
> These tables are almost identical. The only difference is the partially defined columns, which are in response to the separation of concerns principle.

Finally, we're one step away to be done on DB configuration which is creating a bucket called  **banner**. To do that, move into the *storage page* via dashboard > sidebar and create a new bucket called **banner**.

![storage-tutorial](https://ytpmpkgcjlcdidphswzv.supabase.co/storage/v1/object/public/banner/screenshot-2026-09-07-000037-9c56f442.webp)

I'm currently using my bucket publicly because I treat my bucket as an external CDN point for my media elements in my site — idc how unsafe it is so if you think that things in it must remain private then you can leave the toggle state as-is like the one showed above.

### 3. Environment Configuration

Create a brand new env file called `.env` at the root of your project and get the corresponding values of your env keys from project settings of your Supabase organization.

```javascript
SUPABASE_URL=YOUR_PROJECT_URI
SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVICE_ROLE_KEY

APP_TOKEN=YOUT_BASE64_APP_TOKEN
```

After obtaining your DB tokens, replace the placeholder above and only if you do consider to deploy the app to the production, set `APP_TOKEN` to `base64` formatted hash. [You can visit this ](https://it-tools.tech/token-generator)site to generate one in seconds. 

### 4. Database Types

The app uses the typegen for DB types for in particular for React actions. Everything in the `package.json` file is configured for you to invoke codegen but before doing so, you must login to your Supabase account via CLI

Run the CLI command to login your account in your IDE.

```javascript
npx supabase login 
```

This is going to open up a new window inside of your browser to SSO. Follow the instructions given in the CLI to login then run the following command to fetch the DB types

```javascript
npm run db:types
```

### 5. Running the App

Start the development server:
```javascript
npm run dev
```

The current development script starts Next.js on port `36805`:
```javascript
http://localhost:36805
```

That's pretty much everything so far to run the app on locally, it takes max 5 minutes from scratch, I think it's fair. 

## Usage & Writing Your First Article


#### Important Note for Unix-Based OS Developers

It's worth to mention that the **Unix**-based users like mac or linux OS a bit differs in particular scenarios such as key bindings. If you're the one, you may want to configure the app shortcuts in a way that the modifier key `meta` handles the shortcut over `Control` because initially it's defined to `Control` — yes, I'm a windows user.

Simply find the components in your IDE search with a match for the hook imported as:

```javascript
import { useKeyboardShortcut } from "@/hooks/use-keyboard-shortcut";
```

And configure like:

```javascript
  useKeyboardShortcut(
    ["Meta", "/"],
    () => {
     /* INTERNAL CALLBACK */
    },
  ); 
```

***

### Command Center & Shortcuts

> Consider `Ctrl` as `Meta` please Linux & Mac folks

Press `Ctrl + K` to toggle the Command Center, even while editing. Search for a tool, navigate with `↑` / `↓`, and press `Enter` to open its modal. Selecting a tool automatically closes the Command Center.


|                                       Shortcut                                       |                                       Action                                       |
| --- | --- |
|                                       `Ctrl + K`                                       |          Toggle the Command Center                                       |
|                                       `↑` / `↓`                                       |          Navigate tools                                       |
|                                       `Enter`                                       |          Open the selected tool                                       |
|                                       `Esc`                                       |          Dismiss the active dialog                                       |
Available tools: **View Posts**, **View Drafts**, **Create Draft**, **Media Library**, **Manage Drafts**, and **Manage Posts**.

|                                      Shortcut                                      |                                      Purpose                                      |
| --- | --- |
|                                      `Ctrl + M`                                      |          Toggle between rich-text editing and Markdown mode.                                    |
|                                      `Ctrl + /`                                      |          Show or hide the document viewer. Requires a selected post or draft.                          |
|                                      `Ctrl + S`                                      |          Save content changes to the selected draft or post while the document viewer is mounted.                           |
***

If you'd like to publish the posts powered by SSG render power in Next.js Pages router that maximizes your SEO by god knows how many times, you can [take a look at my blog app's Github Repo ](https://github.com/Masculinn/burakdev/blob/main/src/pages/blogs/%5Bslug%5D.tsx)to inspire by. 

## Contributing

Contributions are welcome! Open an issue to report a bug, suggest a feature, or discuss a significant change before starting.
1. Fork the repository and create a branch for your changes.
2. Install dependencies with `npm install`.
3. Start the development server with `npm run dev`.
4. Make your changes, keeping them focused and consistent with the existing architecture.
5. Run `npm run check` and `npm run build` before submitting.
6. Open a pull request describing the changes, any related issues, and how you tested 
7. them. Include screenshots for UI updates.

Keep credentials and environment files out of your commits.

## Acknowledgements

Huge thanks to [this repo ](https://github.com/htmujahid/shadcn-editor)and its hard-working contributors for allowing me to curate their Shadcn Editor! Lovely set of backgrounds are also scraped from [patterns craft](https://patterncraft.fun/) definitely worth to add in your checklist.


A writing and publishing workspace built with Lexical and Supabase, combining rich-text editing, Markdown mode, and on demand pre-compiled MDX previews.

JavaScript Sessions