
<Image alt="Cartoon React atom character pointing at three components and saying 'You need to re-render'" src="react-rerender.png" priority={true} />

Hi, react [Andy](https://en.wiktionary.org/wiki/react_Andy)!

I’ve used React for over six years. I’ve noticed that even skilled programmers often struggle to grasp how React
operates behind the scenes. This can lead to inefficiencies. It affects code quality, speed, and user experience.

The documentation is great for starting with React. Many [books](https://www.roadtoreact.com/), courses, and blogs focus
on beginners. But what comes next? How can you dive deeper and really understand how it works? If you’ve been writing
React for a while, basic or
even intermediate courses may not be enough. Sadly, resources for advanced learning are limited.

That’s why I’m launching a [series of articles](/blog/category/advanced-react) to fill this knowledge gap.

## Intro to re-renders

Understanding re-renders in React is crucial for performance. You need to understand what triggers them. Know how they
move through the app. Learn what happens during a re-render and why it matters.

<Image alt="Meme: 'Oh, so you like React? Tell me what triggers a re-render' with a skeptical cartoon character" src="react-meme.png" />

## The problem

Imagine you're an intern at a FAANG company. Your first task is to create a new React component. You're asked to add a
simple `button` that opens a `settings panel` at the top of the dashboard.

```jsx
const Dashboard = () => {
  // Some code here
  return (
    <div className="container">
      {/* The trigger should go somewhere here */}
      <ExpensiveDataGrid />
      <AnalyticsWidget />
      <ActivityFeed />
    </div>
  );
};
```

Then you implement it. The task seems straightforward. We've all done it countless times:

```jsx
const Dashboard = () => {
  // Add state
  const [isExpanded, setIsExpanded] = useState(false);

  // Everything that is returned here will be re-rendered when the state is updated
  return (
    <div>
      {/* Add the trigger */}
      <IconButton onClick={() => setIsExpanded(true)}>Show settings</IconButton>

      {/* Add the panel */}
      {isExpanded && <SettingsPanel onDismiss={() => setIsExpanded(false)} />}

      <ExpensiveDataGrid />
      <AnalyticsWidget />
      <ActivityFeed />
    </div>
  );
};
```

You add [state](https://react.dev/learn/state-a-components-memory) to track if the panel is expanded or collapsed. You include
a button to change the state and render the panel
based on this state.

When you run the app, there's a noticeable delay ⏰, **almost a second** — before the panel appears.

Experienced React developers might quickly suggest.

> "You’re re-rendering the whole app. Just wrap everything in [React.memo](https://react.dev/reference/react/memo) and
> use [useCallback](https://react.dev/reference/react/useCallback) to avoid unnecessary renders."

This advice has its place, but it’s wise to pause before jumping in. In this case, memoization isn’t needed and could
hurt performance.

First, let’s take a closer look at what exactly is happening and why this delay occurs.

<Image alt="Flowchart showing a state update at the root triggering re-renders in all child components down the tree" src="rerender.png" />

When we click the button, we trigger the `setIsExpanded` setter function, which updates the `isExpanded` state from `false` to
`true`. As a result, the `Dashboard` component that holds this state re-renders itself.

After the state updates and the `App` component re-renders, React must pass the new data to other dependent components.
It automatically re-renders all components that the first component shows. It keeps going down the tree until it reaches
the end.

If you visualize a typical React app as a tree structure, you will find that everything beneath the point where the
state update was initiated will be re-rendered.

> Re-rendering is crucial to understand in React.

The key point to remember is that React never re-renders components "up" the render tree. If a state update occurs in
the middle of the component tree, only the components "down" the tree will be re-rendered.

<Image alt="Component tree diagram where only the subtree below the state update node re-renders, leaving sibling branches unchanged" src="rerender-state.png" />

When a component is wrapped in `React.memo`, `React` will interrupt its default re-rendering process and first evaluate
whether the `props` have changed. If there are no changes to the `props`, re-renders will be halted. However, if even a
single `prop` is modified, the re-rendering will proceed as usual.

It's important to note that effectively preventing re-renders through memoization is a nuanced topic with various
considerations. For a deeper understanding, it is advisable to explore these concepts further in new articles. (Coming soon... or read about [Elements, Children as Props, and Re-Renders](/blog/react-elements-children))

<Image alt="Component tree diagram showing React.memo blocking re-renders on one branch while the other branch re-renders normally" src="react-memo.png" />

Wrapping components with `React.memo` can indeed help prevent unnecessary re-renders in certain scenarios. However, it's
important to note that using `React.memo` comes with its own set of complexities and caveats, which will be discussed in
future articles. A more effective approach is to isolate the components that rely on specific state and encapsulate both
the state and those components into a smaller, dedicated component. This can lead to improved performance and a clearer
component structure.

## Moving state down

Let's move our logic into a separate component.

```jsx
const SettingsToggle = () => {
  const [isExpanded, setIsExpanded] = useState(false);

  return (
    <>
      <IconButton onClick={() => setIsExpanded(true)}>Show settings</IconButton>

      {isExpanded && <SettingsPanel onDismiss={() => setIsExpanded(false)} />}
    </>
  );
};
```

And then render this new component in the `Dashboard`:

```jsx
const Dashboard = () => {
  return (
    <div>
      {/* Our new component */}
      <SettingsToggle />

      <ExpensiveDataGrid />
      <AnalyticsWidget />
      <ActivityFeed />
    </div>
  );
};
```

<Image alt="Before-and-after component tree: moving state into a child component isolates re-renders from the slow sibling component" src="rerender-performance-fix.png" />

Consequently, the settings panel appears immediately. We resolved a significant performance issue using a straightforward
composition technique!


Dive into the mechanics of React re-renders — learn what causes them, how they impact performance, and how to manage them effectively.

React Re-Renders: What Triggers Them and Why


### Understanding the Hidden Pitfalls of Custom Hooks in React

In a previous post we covered [How React Re-Renders Work](/blog/react-rerender). But today, we'll take a closer look at
the hidden pitfalls of custom hooks in React.

<Image alt="Hand-drawn cover image with 'Custom React Hooks' title, useEffect() in blue, fishing hook illustrations, and the React logo" src="hooks.jpg" priority={true} />

When we handle state, component re-renders, and application performance in React, custom hooks are a powerful tool that
help us keep our components clean and manageable. However, this simplicity can sometimes hide performance issues that we
may not immediately notice.

Consider a basic custom hook for managing a dropdown menu:

```jsx
const useDropdown = () => {
  const [isOpen, setIsOpen] = useState(false);

  return {
    isOpen,
    open: () => setIsOpen(true),
    close: () => setIsOpen(false),
    toggle: () => setIsOpen((prev) => !prev),
  };
};
```

Using this hook in a component might look neat and clean:

```jsx
const App = () => {
  const { isOpen, toggle, close } = useDropdown();

  return (
    <div className="app-container">
      <button onClick={toggle}>Menu</button>
      {isOpen && <DropdownMenu onSelect={close} />}
      <ExpensiveChart />
      <DataGrid rows={1000} />
    </div>
  );
};
```

At first glance, this setup appears elegant—state logic neatly wrapped in the `useDropdown` hook. However, this
approach hides a subtle performance issue: whenever the dropdown visibility state changes, React re-renders the entire
`App` component, despite the state being limited to a small interaction.

> Why? You can read more about react rerenders [here](/blog/react-rerender).

### Hidden States and Re-rendering Pitfalls

Let's extend our custom hook to listen for window resize events:

```jsx
const useDropdown = () => {
  const [windowWidth, setWindowWidth] = useState(window.innerWidth);

  useEffect(() => {
    const handleResize = () => setWindowWidth(window.innerWidth);
    window.addEventListener('resize', handleResize);

    return () => window.removeEventListener('resize', handleResize);
  }, []);

  return {
    // For example, this part of the code was simplified
    isOpen: false,
    open: () => {},
    close: () => {},
    toggle: () => {},
  };
};
```

Now, every time the user resizes the window, this hook updates the state internally. Even though the window width isn't
returned or directly used, it **triggers state changes**, causing the entire `App` to re-render unnecessarily.

### Nested Hooks Can Multiply Issues

The problem worsens when custom hooks depend on other hooks indirectly. For example, consider another hook for tracking
keyboard input:

```jsx
const useKeyboardListener = () => {
  const [lastKey, setLastKey] = useState(null);

  useEffect(() => {
    const handleKeyDown = (e) => setLastKey(e.key);
    window.addEventListener('keydown', handleKeyDown);

    return () => window.removeEventListener('keydown', handleKeyDown);
  }, []);

  return lastKey;
};

const useDropdown = () => {
  useKeyboardListener();

  return {
    // For example, this part of the code was simplified
    isOpen: false,
    open: () => {},
    close: () => {},
    toggle: () => {},
  };
};
```

Even if `useDropdown` does not directly use the last key pressed, the `App` component still re-renders each time
a key is pressed, since the state is updated inside the nested hook.

> Hiding stateful logic within hooks doesn't remove their performance impact. The
> solution isn’t hiding complexity but smartly managing and isolating the state.

### How to Solve This

To avoid such issues, encapsulate state logic in smaller components:

```jsx
const Dropdown = () => {
  const { isOpen, toggle, close } = useDropdown();

  return (
    <>
      <button onClick={toggle}>Menu</button>
      {isOpen && <DropdownMenu onSelect={close} />}
    </>
  );
};
```

This ensures that the minimal required area re-renders, preventing unnecessary updates across the entire app.

> In this solution, the `Dropdown` logic moved down from `App` to its own component. I described this approach in
> [this article](/blog/react-rerender#moving-state-down).

### Key Takeaway

The key lesson: carefully handle state encapsulation within custom hooks. Keep state management local and focused to
optimize your React application's performance and responsiveness.

> P.S. Memoization and other performance optimizations will be covered in future posts. Meanwhile, you can read about [Elements, Children as Props, and Re-Renders](/blog/react-elements-children).

## Related

- [useClickOutside Hook](/snippets/use-click-outside) - a practical custom hook example that applies the patterns discussed above
- [useMediaQuery Hook](/snippets/use-media-query) - another commonly used custom hook with proper cleanup


Learn about performance risks in React custom hooks, how they cause unexpected re-renders, and strategies to manage state efficiently.

Understanding the Hidden Pitfalls of Custom Hooks in React


Welcome back, fellow React enthusiasts!

Previously, we discussed [re-renders and the "moving state down" pattern](/blog/react-rerender). That technique works
great when you can isolate stateful logic into a leaf component. But sometimes the architecture doesn't allow for that.

What do you do when state _must_ live at the top, yet you don't want to tank performance?

Let's explore a real scenario. You're building a dashboard with a resizable sidebar. The sidebar width is controlled
by dragging a handle, and the entire content area needs to respond to this width change.

## The Challenge

Here's what you need:

- A draggable divider that updates the sidebar width in real-time.
- The sidebar wraps around `ExpensiveChart`, `DataGrid`, and `AnalyticsPanel`.
- As you drag, the layout adjusts smoothly.

The naive approach puts the drag state at the top level (or perhaps tries to hide it in
a [custom hook](/blog/react-hooks-pitfalls), which doesn't change anything):

```jsx
const Dashboard = () => {
  const [sidebarWidth, setSidebarWidth] = useState(300);

  const handleDrag = (e) => {
    setSidebarWidth(e.clientX);
  };

  return (
    <div className="dashboard-layout">
      <div className="sidebar" style={{ width: sidebarWidth }}>
        <DragHandle onDrag={handleDrag} />

        {/* These re-render constantly while dragging! */}
        <ExpensiveChart />
        <DataGrid />
        <AnalyticsPanel />
      </div>
      <MainContent />
    </div>
  );
};
```

<Image src="elements.png" alt="React DevTools screenshot titled 'The Problem: Re-rendering Everything' showing App component with scrollPosition state triggering re-renders on BunchOfStuff and VerySlowComponent children" />

This implementation will stutter badly. Every mouse movement fires a state update, causing `Dashboard` to re-render.
When `Dashboard` re-renders, so does everything nested inside it. The "moving state down" approach fails here because
the `sidebar` div needs to wrap the expensive components while also knowing about the width.

You might reach for `React.memo`, but there's a cleaner compositional approach that leverages how React handles
elements.

## The Fix: Composition with Children

Extract the resize logic into a dedicated component that accepts its contents as children:

```jsx
const ResizableSidebar = ({ children }) => {
  const [width, setWidth] = useState(300);

  const handleDrag = (e) => {
    setWidth(e.clientX);
  };

  return (
    <div className="sidebar" style={{ width }}>
      <DragHandle onDrag={handleDrag} />
      {children}
    </div>
  );
};
```

Refactor `Dashboard` to use this wrapper:

```jsx
const Dashboard = () => {
  return (
    <div className="dashboard-layout">
      <ResizableSidebar>
        {/* Passed as props, not defined here */}
        <ExpensiveChart />
        <DataGrid />
        <AnalyticsPanel />
      </ResizableSidebar>
      <MainContent />
    </div>
  );
};
```

Now dragging is fluid. The expensive components stay untouched even though they visually live inside a component that
updates dozens of times per second.

## The Mechanics Behind It

This behavior stems from the distinction between **Components** and **Elements**.

A **Component** is the function itself (`Dashboard`, `ResizableSidebar`).

An **Element** is the object produced when JSX executes (`{ type: ExpensiveChart, props: {...} }`).

Here's what happens step by step:

1. `Dashboard` renders once and creates Element objects for `<ExpensiveChart />`, `<DataGrid />`, and
   `<AnalyticsPanel />`.
2. These Element objects get passed into `ResizableSidebar` through the `children` prop.
3. User starts dragging. `ResizableSidebar` updates its `width` state repeatedly.
4. `ResizableSidebar` re-executes, returning a new sidebar div with the updated width.
5. React checks the `children` prop. Has the reference changed?
6. No. `Dashboard` never re-rendered, so `children` points to the exact same objects in memory.
7. React skips reconciling that entire subtree.

The key insight: **React compares element references, not their visual position in the tree.**

## Understanding the JSX Transformation

Remember that `children` is an ordinary prop. The nested syntax is syntactic sugar.
Elements are [expressions](/blog/expressions-statements), so these two snippets produce identical results:

```jsx
<Wrapper>
  <Content />
</Wrapper>
```

```jsx
<Wrapper children={<Content />} />
```

You could use any prop name: `content`, `slot`, `body`. The optimization works as long as the Element is created in a
scope that doesn't re-render and then passed to the stateful component.

## Wrapping Up

The [previous article](/blog/react-rerender#moving-state-down) showed how pushing state into a child component
prevents unnecessary re-renders. This article demonstrated the inverse: lifting static UI _out_ of the stateful
component by passing it as props.

Both patterns serve the same purpose: decoupling what changes from what stays stable.


Learn how React elements work and how passing children as props can optimize performance by preventing unnecessary re-renders.

React Elements, Children as Props, and Re-Renders


## The number that didn't move

I pushed a routine update to my portfolio — swapped Prettier for [oxfmt](https://github.com/nicolo-ribaudo/oxfmt),
added [`@shikijs/transformers`](https://shiki.style/packages/transformers) for better syntax highlighting. Stack is
Next.js 16, Turbopack, Prisma, Sentry, Vercel, pnpm. Nothing unusual.

Checked the [Vercel build log](https://vercel.com/docs/deployments/logs). Total build time: 48 seconds. Ran two more deploys to be sure. 47 seconds. 48 seconds.
Flat line.

I almost closed the tab.

Then I scrolled down to the per-page breakdown. Completely different story.

## Two changes, opposite directions

The listing pages — homepage, blog index, snippets — got much faster:

| Route       | Before   | After  |
| ----------- | -------- | ------ |
| `/`         | 7,046 ms | 487 ms |
| `/blog`     | 7,116 ms | 664 ms |
| `/snippets` | 7,046 ms | 547 ms |

Roughly a 13x improvement. But the total build time didn't budge. Something else got worse by the same amount.

That something was `/blog/category/[category]`.

| Metric           | Before       | After        |
| ---------------- | ------------ | ------------ |
| Route total      | ~15.8 s      | ~45.8 s      |
| Slowest category | ~1,000 ms    | ~6,600 ms    |
| Typical range    | 900–1,100 ms | 500–6,600 ms |

Six categories jumped from about a second to 6.6 seconds each: `html`, `clean-code`, `project-setup`, `node`, `react`,
`advanced-react`. The rest stayed put. A 20-second improvement on listing pages masked a 30-second regression on
category pages. Near-perfect cancellation.

> An accidental coincidence that made the top-line number useless.

## The wrong fix

Three deploys. Same six slow categories. Same order of magnitude. Not noise.

The six categories had something in common — they were the six with the most posts. Whatever was slow, it scaled with
post count.

My hypothesis: the category page was fetching full post content — markdown body included — when it only needed metadata.
A listing page shows titles, descriptions, and links. It doesn't render post bodies. If the data-fetching function
pulled full content, it was doing unnecessary work.

I checked the code. [`getPostsByCategory`](https://github.com/Shramkoweb/Portfolio/blob/47abb02/lib/posts/api.ts#L171-L174) called [`getPosts`](https://github.com/Shramkoweb/Portfolio/blob/47abb02/lib/posts/api.ts#L109-L120), which reads every post file and returns the body. The
category page never used the body. I switched it to [`getPostsMetadata`](https://github.com/Shramkoweb/Portfolio/blob/843ae89/lib/posts/api.ts#L122-L133) — slug, title, description. No body. Two files,
28 lines changed.

Deployed. Checked the build log.

**Numbers didn't move.** Same six categories. Same 6,600ms each.

## The actual problem

I stared at the build log longer and noticed something I'd skipped over. Look at these two routes:

```text
/blog/[slug]                     (43168 ms)
  /blog/ai-seo-audit             (6663 ms)
  /blog/apollo-graphql-certification (6663 ms)

/blog/category/[category]        (45771 ms)
  /blog/category/html            (6663 ms)
  /blog/category/clean-code      (6663 ms)
```

Blog posts and category pages both showing exactly 6,663ms. Not approximately — _exactly_.
Different routes, different code paths, identical timing.

Next.js [generates static pages in batches](https://nextjs.org/docs/app/api-reference/config/next-config-js/staticGeneration). The per-page time in the build log is the batch wall-clock time, not the
individual page time. Every page in a batch gets assigned the same number — the slowest page in that batch.

My category pages were fast. They were just stuck in the same batch as Shiki-heavy blog post compilations. The metadata
fix was correct code hygiene — don't fetch content you don't need — but it couldn't change the batch timing because the
category pages weren't the bottleneck in their batch. The blog posts were.

## The real bottleneck

So why were the blog posts slow? I dug into the [Shiki integration](https://github.com/Shramkoweb/Portfolio/blob/47abb02/lib/scripts/compiler.ts).

Every [`compileMDX`](https://github.com/Shramkoweb/Portfolio/blob/47abb02/lib/scripts/compiler.ts#L9-L45) call created a new `rehypeShiki` plugin instance. Each instance initialized a fresh Shiki
highlighter — loading the WASM engine, two themes, and grammars for every bundled language.

> 34 pages = 34 highlighter initializations.

The fix: use `@shikijs/rehype/core` with a single [pre-created highlighter](https://github.com/Shramkoweb/Portfolio/blob/843ae89/lib/scripts/compiler.ts#L10-L19) at module level.

```ts
import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
import { bundledLanguages, getSingletonHighlighter } from 'shiki';

const highlighterPromise = getSingletonHighlighter({
  themes: ['github-light', 'github-dark'],
  langs: Object.keys(bundledLanguages),
});

const highlightCache = new Map();
```

Themes and language grammars load once. A shared `Map` caches highlighted code blocks across pages. The pre-created
highlighter gets passed directly to each `compileMDX` call instead of creating a new one.

Same Vercel infrastructure, same 1 worker:

| Metric                  | Before    | After     |
| ----------------------- | --------- | --------- |
| Static generation total | 13.4 s    | 6.7 s     |
| `/blog/category` route  | 45,771 ms | 7,396 ms  |
| Category per-page       | 6,663 ms  | 461 ms    |
| `/blog/[slug]` route    | 43,168 ms | 27,770 ms |

The category route dropped from 45.8s to 7.4s. Individual categories went from 6,663ms to 461ms. Static generation cut
in half.

You might notice those route totals don't add up. Before the fix, `/blog/[slug]` showed 43s, `/blog/category` showed
45s, `/snippets` showed 14s — that's 102 seconds of work. But actual static generation took 13.4s. The route times are
concurrent, not sequential. Next.js generates multiple routes at the same time; each route's clock runs in parallel.

> The total build went from 46s to 42s because static generation is only one piece — TypeScript checking, Turbopack
> compilation, and Sentry uploads don't get faster when you fix Shiki.

## Three things I got wrong

First, I thought the category page was the problem. It wasn't — it was an innocent bystander in a slow batch.

Second, I thought `getPostsMetadata` vs `getPosts` was the fix. It was good code, but it didn't address the timing. I
was looking at the right page and the wrong metric.

Third, I assumed per-page timing in the build log meant per-page timing. It means per-batch timing. Every page in a
batch gets the same number. If you're comparing page performance across builds, you're comparing batch composition and
scheduling as much as you're comparing the page itself.

## The numbers you actually need

Total build time is the number everyone watches. It's on the dashboard. It's in the Slack notification. It's the number
you compare week over week.

It's also an aggregate, and aggregates lie by averaging. My total build time held steady at 48 seconds while a 30-second
per-route regression hid behind an equally sized improvement somewhere else.

And when I looked at the per-page numbers, those lied too — just differently. They told me which pages were slow. They
didn't tell me those pages were _fast_, just stuck behind slow neighbors.

I ended up fixing the right thing for the wrong reason. I'll take it.


I spotted a build regression, shipped what I thought was the fix, and the numbers didn't move. Turns out the metrics were lying too — Next.js reports batch timing, not page timing.

I Fixed the Wrong Thing and Found the Real Bug


<Image alt="A hand-drawn diagram showing Generic Type Parameters on the left and a browser window with TypeScript code for a generic identity function on the right, plus two boxes labeled U and V" src="generic.jpg" priority={true} />

When you first encounter TypeScript generics, you'll likely see something
like [this](https://www.typescriptlang.org/docs/handbook/2/generics.html#hello-world-of-generics):

```typescript
function identity<T>(arg: T): T {
  return arg;
}
```

That lonely **T** sitting there might seem mysterious.

Why T? What if you need more than one? And when should you graduate from single letters to something more descriptive?
Let's dive into the world of generic naming conventions and figure out what actually makes sense.

## The Classic Lineup: T, U, V, W

The **T** convention comes from mathematics and early programming languages. It simply stands for "Type" – nothing
fancy.
When you need multiple generic parameters, the tradition is to march through the alphabet:

```typescript
// Two types? Add U
function pair<T, U>(first: T, second: U): [T, U] {
  return [first, second];
}

// Three types? Bring in V
function triple<T, U, V>(first: T, second: U, third: V): [T, U, V] {
  return [first, second, third];
}
```

This alphabetical progression isn't arbitrary – it creates a clear, predictable pattern that developers can follow
easily. Plus, these single letters are visually distinct and don't clutter your code.

> This naming convention is common in different languages,
> like [Java](https://docs.oracle.com/javase/tutorial/java/generics/types.html) and others.

## When Single Letters Work Perfectly

For simple, general-purpose functions and utilities, single letters are your best friend:

```typescript
// Array mapping - crystal clear what T and U represent
function map<T, U>(items: T[], transform: (item: T) => U): U[] {
  return items.map(transform);
}

// Key-value pairs - K and V are intuitive
interface Dictionary<K, V> {
  [key: K]: V;
}
```

> Notice how TypeScript's own built-in utilities follow this pattern. `Pick<T, K>`, `Omit<T, K>`, `Record<K, V>` – they
> stick with meaningful single letters because the context makes their purpose obvious.

## The Case for Descriptive Names

Sometimes, though, single letters leave your future self (and your teammates) scratching their heads. That's when
descriptive names shine:

```typescript
// What are T and U supposed to represent here?
interface ApiClient<T, U> {
  get(endpoint: string): Promise<T>;
  handleError(error: U): void;
}

// Much clearer!
interface ApiClient<ResponseData, ErrorType> {
  get(endpoint: string): Promise<ResponseData>;
  handleError(error: ErrorType): void;
}
```

This is especially valuable in domain-specific code where the generic types have special meaning in your business logic.

## The Repository Pattern Example

Here's where descriptive naming really pays off:

```typescript
interface Repository<Entity, Key> {
  findById(id: Key): Promise<Entity | null>;
  save(entity: Entity): Promise<Key>;
  delete(id: Key): Promise<void>;
  findAll(): Promise<Entity[]>;
}

class UserRepository implements Repository<User, string> {
  // Implementation details...
}
```

Anyone reading this code immediately understands what **Entity** and **Key** represent.
Compare that to `Repository<T, U>` – you'd need to dig into the implementation to figure out which is which.

## The T Prefix Debate

You'll sometimes see generic parameters prefixed with T:

```typescript
interface Repository<TEntity, TKey> {
  findById(id: TKey): Promise<TEntity>;
}
```

This convention comes from [C#](https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic?view=net-9.0) and serves a purpose – it clearly marks something as a **type parameter** rather than a
**regular variable**. But it's not universally loved.

TypeScript's own standard library doesn't use the T prefix.
React components rarely use it. Many JavaScript and TypeScript projects skip it entirely:

```typescript
// Both are perfectly valid
interface Props<User, Settings> {}
interface Props<TUser, TSettings> {}
```

The choice often comes down to team preference and consistency with your existing codebase. Pick one style and stick
with it.

## Practical Guidelines

Here's what I've learned from years of writing TypeScript:

### Use single letters when:

- Writing utility functions that work with any type
- The generic's role is obvious from context
- You're following established patterns (like `map<T, U>`)

### Use descriptive names when:

- The generics have a specific domain meaning
- You have multiple related type parameters
- Code clarity would suffer with single letters

### Stay consistent:

- Whatever convention your team chooses, apply it everywhere
- Don't mix T prefixes with non-prefixed names randomly
- Document your team's preferred style

## Common Single-Letter Conventions

```typescript
T; // Primary type parameter
(U, V, W); // Additional type parameters (alphabetical order)
K; // Key type (in mappings, records)
V; // Value type (in key-value structures)
E; // Element type (in collections)
R; // Return type
P; // Properties/Props type
```

## Wrapping Up

- **Consistency beats perfection** – pick a style and stick with it
- **Context is king – choose names** that make sense for your specific use case
- **When in doubt, be descriptive** – clarity trumps brevity in complex code
- **Follow your team's conventions** – consistency across the codebase matters most

> I love conventions and wrote a lot of articles about them.
> Check out about [conventional commits](/blog/conventional-commits) and [JavaScript Naming](/blog/javascript-naming-conventions) for more.

## Related

- [Template Literal Types](/snippets/template-literal-types) - template literal types leverage generics for powerful string patterns
- [The satisfies Operator](/snippets/satisfies-operator) - satisfies uses type inference alongside generics
- [Discriminated Unions](/blog/discriminated-unions) - combine unions with generics for type-safe patterns


Learn TypeScript generic type parameter naming conventions. Understand when to use T, K, V and when descriptive names like TKey make your code more readable.

What is a generic type parameter T in TypeScript?


If you’re interested in GraphQL but haven’t had the chance to explore it directly, it's time to take action.
[Apollo Odyssey](https://www.apollographql.com/tutorials/) is the perfect solution to help you understand how it all
fits together!

<Image alt="Apollo Certified Graph Developer Associate certificate issued to Serhii Shramko on 3/12/2025" src="graphql-certificate.png" priority={true} />

## Apollo Odyssey: Free Learning Platform

The learning platform features a variety of paths, combining video tutorials with written guides that include quizzes
and code challenges for reinforcement.

<Image alt="Apollo Odyssey learning platform video showing Track Card data structure with fields: title, thumbnail, length, module count, author name, and author picture" src="graphql-apollo-odyssey.png" />

To earn
the [Apollo Graph Developer - Associate certification](https://www.apollographql.com/tutorials/certifications/apollo-graph-associate),
you must complete the first four paths:

- [Basics](https://www.apollographql.com/tutorials/lift-off-part1)
- [Resolvers](https://www.apollographql.com/tutorials/lift-off-part2)
- [Arguments](https://www.apollographql.com/tutorials/lift-off-part3)
- [Mutations](https://www.apollographql.com/tutorials/lift-off-part4)

> Developers who obtain this certification possess a solid foundational knowledge of GraphQL and the Apollo tool suite
> to design a schema, run an Apollo Server 4, and perform queries with Apollo Client 3 on the frontend.

I absolutely love this platform! It features fantastic videos, clear explanations, and some really good jokes that
always make me smile. 😀

## Apollo Graph Developer - Associate

As you work your way through the four required tutorials, you will be creating a real-world application called
`Catstronauts`.

<Image alt="Catstronauts demo app built with React and GraphQL showing a grid of cat-themed space course cards" src="catstronauts.png" />

This project consists of a frontend client built with _TypeScript_ and _React_, alongside a backend server that utilizes
_Node.js_ as its runtime environment and [Apollo Server](https://www.apollographql.com/docs/apollo-server) as a
standalone, spec-compliant GraphQL server.

## Certification exam

- 31 multiple choice questions
- 25 correct answers required to pass

I achieved success in my test, making only a single error.

This outcome highlights the effectiveness of the course, which comprehensively addresses all relevant material,
equipping me with the confidence to approach the exam calmly.

## Graph Developer - Professional

Well, now the next step is to gain a deeper knowledge of GraphQL and
get [Graph Developer - Professional](https://www.apollographql.com/tutorials/certifications/apollo-graph-professional)
certification.

> Developers who obtain this certification demonstrate strong familiarity with Apollo Federation concepts. They can
> apply those concepts to build a federated supergraph or move an existing monolithic graph to federation.

I really commend the [Raphael Terrier](https://www.linkedin.com/in/raphaelterrier/)
and [Michelle Mabuyo](https://www.linkedin.com/in/michellemabuyo/) for developing such an excellent learning course.

## Further reading

- [Useful Articles for Developers](/blog/useful-articles) — curated list of recommended developer resources
- [Branded Types in TypeScript](/snippets/branded-types) — type safety technique useful for strongly-typed GraphQL schemas


My journey to getting Apollo GraphQL certification for free. Learn about the exam structure, preparation tips, and how to earn your credential.

How I Got Apollo GraphQL Certification for Free

<Image alt="Shiki syntax highlighter logo on a dark background, representing class-based theme extraction for Next.js MDX blogs" src="shiki.jpg" />

When your blog has 30+ code-heavy posts, Shiki's default dual-theme output dumps two sets of inline styles on
every `<span>` — one for light, one for dark. That's a lot of repeated CSS baked into your HTML. I switched to
`transformerStyleToClass` and cut the per-page highlighting payload by deduplicating those styles into a single CSS
block. Here's how I wired it up.

## The problem with inline dual themes

Shiki's standard dual-theme mode writes both color values directly onto each token:

```html

<span style="color:#24292e;--shiki-dark:#e1e4e8">const</span>
```

Multiply that across hundreds of tokens and two themes. Every page carries duplicated color strings that can't be
cached or shared between posts.

## Switch to class-based output

`transformerStyleToClass` from `@shikijs/transformers` replaces inline styles with hashed class names. You create one
transformer instance at module level — this matters because the cache and the CSS accumulate across all posts during a
single build:

```typescript
// lib/scripts/compiler.ts
import rehypeShikiFromHighlighter from '@shikijs/rehype/core';
import { transformerStyleToClass } from '@shikijs/transformers';
import { serialize } from 'next-mdx-remote/serialize';
import { bundledLanguages, getSingletonHighlighter } from 'shiki';

const highlighterPromise = getSingletonHighlighter({
  themes: ['github-light', 'github-dark'],
  langs: Object.keys(bundledLanguages),
});

// Module-level: accumulates class→variable mappings across all posts
const transformer = transformerStyleToClass();
const highlightCache = new Map();

export async function compileMDX(content: string) {
  const highlighter = await highlighterPromise;

  const mdx = await serialize(content, {
    mdxOptions: {
      rehypePlugins: [
        [
          rehypeShikiFromHighlighter,
          highlighter,
          {
            themes: { light: 'github-light', dark: 'github-dark' },
            defaultColor: false,
            transformers: [transformer],
            cache: highlightCache,
          },
        ],
      ],
    },
  });

  return { mdx, shikiCSS: transformer.getCSS() };
}
```

Two things to notice. First, `defaultColor: false` tells Shiki not to pick a winner — both themes live as CSS custom
properties on the generated classes. Second, the `highlightCache` skips re-processing identical code blocks across
posts, so the transformer must be a singleton to keep its internal class-to-style map complete.

## Inject the CSS per page

In your page component, `getStaticProps` passes `shikiCSS` alongside the serialized MDX. Drop it into `<Head>` so the
styles exist before any code block renders:

```tsx
// pages/blog/[slug].tsx
export async function getStaticProps({ params }: GetStaticPropsContext) {
  const { data, content } = await getPostBySlug(params?.slug);
  const { mdx, shikiCSS } = await compileMDX(content);

  return { props: { data, content: mdx, shikiCSS } };
}

function ArticlePage({ content, shikiCSS, data }: ArticlePageProps) {
  return (
    <>
      <Head>
        <title>{data.title}</title>
        {shikiCSS && <style dangerouslySetInnerHTML={{ __html: shikiCSS }} />}
      </Head>
      <MDXRemote {...content} components={MDXComponents} />
    </>
  );
}
```

Your theme toggle handles the rest. In dark mode, generated classes apply `--shiki-dark` values; in light mode,
`--shiki-light`. No JavaScript runs at highlight time.

## One gotcha

If you create a _new_ transformer instance per `compileMDX` call, posts compiled after a cache hit return empty CSS —
the cache skips the transformer entirely, so a fresh instance never sees those tokens. Keep the transformer at module
scope.

## Related

- [Total Build Time Lies](/blog/build-time-lies) — how I found and fixed a Shiki performance regression in this same
  codebase

Replace Shiki's bloated inline dual-theme styles with class-based CSS extraction using transformerStyleToClass and next-mdx-remote in Next.js.

How to Use Shiki Class-Based Themes with next-mdx-remote in Next.js


<Image src="seo.jpg" alt="Website analytics dashboard showing real-time user count, traffic graphs, revenue metrics, and top countries" priority={true} />

I've been putting off an SEO audit of my blog for months. With **30+** articles and **20+** code snippets, the task felt overwhelming. Reviewing each meta description, checking for broken links, validating alt text — it's the kind of work that's _easy to procrastinate_ on indefinitely.

Then I tried something different: I used AI as my editorial assistant. In a single afternoon, I audited and improved **56 files**. Here's how it went.

## The Boring Work Nobody Wants to Do

Let's be honest — SEO maintenance is _boring_. It's not the exciting part of running a developer blog. You know you should do it, but there's always something more interesting to work on.

My blog had accumulated typical SEO debt over time. Generic meta descriptions that said nothing specific, like "Learn about X" instead of actual summaries. Broken external links because MDN reorganized their docs and Git changed their download URL. Empty alt attributes on images where I'd rushed through posts and left `alt=""`. The usual mess.

Fixing this manually would mean opening each file, reading the content, rewriting descriptions, and validating every link. For 56 files? That's a full weekend I'd _never_ actually spend.

## Teaching AI What I Need

The key insight was treating AI not as a magic "fix everything" button, but as a _focused assistant_ with clear constraints. I use [Cursor](https://www.cursor.com/) as my editor, and it supports [project-specific rules](https://docs.cursor.com/context/rules) — markdown files that act as persistent instructions for the AI.

I created a rules file (`.cursor/rules/seo.mdc`) that defined exactly what I needed:

```markdown
SEO responsibilities:

- Propose 2–5 realistic, developer-focused keyword phrases for each article
- Suggest an SEO-friendly title (50-60 characters) and meta description (110-160 characters)
- Naturally integrate the main keyword into title, first paragraph, and conclusion
- Never sacrifice clarity or honesty for SEO
```

This file acts as persistent context. Every time the AI reviews an article, it knows who I am (a senior software engineer), who my audience is (developers from junior to senior level), my writing style (conversational, direct, technical), and what to avoid (inventing experience, adding buzzwords, breaking code).

That last constraint — _"never sacrifice clarity for SEO"_ — is crucial. I've seen AI-generated content stuffed with keywords that reads like garbage. That's not what I wanted.

## What the SEO Audit Found

<Image src="ahrefs-audit.png" alt="Ahrefs Site Audit project history for shramko.dev showing 100% health score across 370 crawls with URLs crawled and total issues charts" />

**Before:**

```text
description: Polymorphism and Dispatch Tables in JS
```

**After:**

```text
description: Replace messy switch statements with dispatch tables in JavaScript.
Learn this clean code pattern for handling multiple conditions with maintainable code.
```

The first one tells you nothing. The second _explains the benefit_, uses action words, and includes relevant keywords naturally.

MDN restructured their documentation URLs at some point too. Links that worked a year ago now 404. The AI flagged these:

```diff
- [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout)
+ [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Grid_layout)
```

Same for Flexbox and other external resources. Small fixes, but broken links hurt both SEO and user experience.

Then there was alt text. In my React re-renders article, I had multiple images with _empty_ alt attributes:

```diff
- <Image alt="" src="rerender.png" />
+ <Image alt="Diagram showing React component tree re-rendering when state updates" src="rerender.png" />
```

The AI suggested appropriate descriptions based on the surrounding content in seconds.

## Wrapping Up

The goal here isn't to automate away quality control. It's to make the tedious parts _fast enough_ that you actually do them.

By the end of the afternoon: **56 files** updated, **50+ meta descriptions** rewritten, **6 broken links** fixed, **12 empty alt attributes** filled.

## Further reading

- [Introducing the New shramko.dev](/blog/introducing-the-new-shramko.dev) — how the blog was built and the tech stack behind it
- [Conventional Commits](/blog/conventional-commits) — another developer tooling practice that keeps your workflow consistent


I used Cursor AI to audit SEO across 56 blog posts in one afternoon. Meta descriptions, broken links, and alt text — all fixed systematically.

I Ran an AI SEO Audit on 56 Blog Posts in One Day


<Image src="exit.jpg" alt="Glowing green EXIT sign hanging from a ceiling, representing how early return pattern lets functions exit before reaching the end" />

**The early return pattern** (also called guard clauses or the bouncer pattern) is a technique where you exit a function as soon as a precondition fails, instead of wrapping your main logic in nested `if` blocks. It reduces nesting, lowers cognitive load, and makes your functions dramatically easier to read.

## What Is the Early Return Pattern?

Today, while wrestling with some code, I caught myself smiling at something small but powerful. I was deep in a function that was starting to look like a staircase of if statements. Halfway through, I stopped and thought: _why am I dragging all these checks down the page when I could just step out early_?

That's when it clicked — again 🥳. Early return isn't just a coding pattern; it's a way of freeing your own brain. You handle the simplest, most obvious cases first and politely bow out of the function. Then the rest of the logic can flow without carrying the weight of those initial conditions.

```javascript
function processUser(user) {
  if (!user) return; // nothing to process
  if (!user.isActive) return; // skip inactive users

  sendWelcomeEmail(user);
  updateAnalytics(user);
}
```

Each of those `if` lines is a **guard clause** — a check that says "if this condition isn't right, leave now." Some people call this the **fail-fast approach**: deal with the problems up front, then focus on the happy path. Others use the term **bouncer pattern** — like a bouncer checking IDs before letting you into a club.

## Before and After: Nested If vs Guard Clauses

Before I got into this habit, my functions often looked like a pile of _stacked boxes — each_ if wrapped inside another. It worked, but it forced every reader (including future me) to carry all those checks in their head all the way down.

```javascript
// ❌ Nested approach
function processUser(user) {
  if (user) {
    if (user.isActive) {
      if (user.hasProfile) {
        sendWelcomeEmail(user);
        updateAnalytics(user);
      }
    }
  }
}
```

This still runs fine, but it makes you think about conditions long after you should've moved on. Now compare:

```javascript
// ✅ Early return approach
function processUser(user) {
  if (!user) return;
  if (!user.isActive) return;
  if (!user.hasProfile) return;

  sendWelcomeEmail(user);
  updateAnalytics(user);
}
```

Once those guard clauses are in place, I don't have to `mentally juggle` those "what ifs" anymore. They're dealt with. The rest of the code reads like a straight road.

> You make the easy decisions first, exit where needed, and leave the interesting logic standing in the light. It's not just about fewer braces — it's about respecting your own attention span.

## The Arrow Anti-Pattern and the Pyramid of Doom

When nested if statements stack up, the code starts forming a visual arrow pointing to the right — this is called the **arrow anti-pattern** (or the **pyramid of doom**). Here's an extreme but not unrealistic example:

```javascript
// ❌ Arrow anti-pattern
function handlePayment(order) {
  if (order) {
    if (order.items.length > 0) {
      if (order.paymentMethod) {
        if (order.paymentMethod.isValid) {
          if (order.shippingAddress) {
            processPayment(order);
            sendConfirmation(order);
          }
        }
      }
    }
  }
}
```

Every condition pushes the real logic further to the right. By the time you reach `processPayment`, you're five levels deep. Early return flattens this completely:

```javascript
// ✅ Flat with guard clauses
function handlePayment(order) {
  if (!order) return;
  if (order.items.length === 0) return;
  if (!order.paymentMethod) return;
  if (!order.paymentMethod.isValid) return;
  if (!order.shippingAddress) return;

  processPayment(order);
  sendConfirmation(order);
}
```

Same logic, zero nesting. The intent is immediately clear: handle the edge cases, then do the work.

## Guard Clauses in Real-World JavaScript

Trivial examples are easy to agree with. Where early return really shines is in production code.

### Express.js API Handler

```javascript
app.post('/api/orders', async (req, res) => {
  if (!req.body.items?.length) {
    return res.status(400).json({ error: 'Cart is empty' });
  }

  if (!req.user) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  if (!req.user.hasPermission('create_order')) {
    return res.status(403).json({ error: 'Forbidden' });
  }

  const order = await createOrder(req.body, req.user);
  return res.status(201).json(order);
});
```

Notice the `return` before each `res.status(...)`. This is critical in Express — without it, the function keeps executing and you'll get "headers already sent" errors. More on this in the [common mistakes](#common-mistakes-with-early-return) section below.

### Form Validation

```javascript
function validateForm(data) {
  if (!data.email) return { valid: false, error: 'Email is required' };
  if (!data.email.includes('@'))
    return { valid: false, error: 'Invalid email' };
  if (!data.password) return { valid: false, error: 'Password is required' };
  if (data.password.length < 8)
    return { valid: false, error: 'Password too short' };

  return { valid: true, error: null };
}
```

Each guard returns a clear error. No nested if-else chains, no accumulated error variables.

### React Component

```jsx
function UserProfile({ user, isLoading, error }) {
  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!user) return <EmptyState />;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.bio}</p>
    </div>
  );
}
```

React developers use this pattern constantly. Each guard clause handles a specific UI state, keeping the main render clean.

## Early Return in TypeScript

Guard clauses in TypeScript do more than improve readability — they **narrow types**. TypeScript understands that after a guard, the remaining code can assume a more specific type.

```typescript
function formatUserName(user: User | null | undefined): string {
  if (!user) return 'Anonymous';
  if (!user.firstName) return user.email;

  // TypeScript knows user is non-null and firstName exists here
  return `${user.firstName} ${user.lastName ?? ''}`.trim();
}
```

This is especially useful with [discriminated unions](/blog/discriminated-unions):

```typescript
type Result =
  | { status: 'success'; data: Order }
  | { status: 'error'; message: string }
  | { status: 'loading' };

function renderResult(result: Result) {
  if (result.status === 'loading') return <Spinner />;
  if (result.status === 'error') return <Error message={result.message} />;

  // TypeScript narrows to { status: 'success'; data: Order }
  return <OrderDetails order={result.data} />;
}
```

No type assertions needed. The guard clauses do the narrowing for you. For reusable checks, you can extract them into [type predicates](/snippets/type-predicates) — custom type guards that make the narrowing explicit.

## Early Return with Async/Await

Early return works just as well in async functions. This is an area where surprisingly few articles give concrete examples, but it's where I find guard clauses most valuable — async code is already hard enough to read without adding nesting.

```javascript
async function fetchUserOrders(userId) {
  if (!userId) return [];

  const user = await getUser(userId);
  if (!user) return [];
  if (!user.isActive) return [];

  const orders = await getOrders(user.id);
  if (!orders.length) return [];

  return orders.map(formatOrder);
}
```

Each guard prevents unnecessary `await` calls. If the user doesn't exist, we skip the orders fetch entirely. This matters for performance — not just readability.

You can combine early returns with `try/catch` as well:

```javascript
async function processWebhook(payload) {
  if (!payload?.event) return { status: 'ignored' };
  if (!isValidSignature(payload)) return { status: 'unauthorized' };

  try {
    const result = await handleEvent(payload.event, payload.data);
    return { status: 'processed', result };
  } catch (error) {
    return { status: 'failed', error: error.message };
  }
}
```

The guard clauses stay clean and outside the `try/catch` — no need to catch errors for validations that won't throw.

## Early Return vs Nested If Statements

Some developers argue that early return "splits" the function into multiple exit points, making it harder to trace. Let me address that honestly.

Nested if statements have **one** exit point — the end of the function. Early return can have **many**. So which is better?

In practice, **multiple early exits are easier to reason about** because each one is self-contained. When you see `if (!user) return;`, you know exactly what happens for that case. With nested ifs, you have to trace through the entire tree to understand every path.

That said, if your function has only one or two conditions, nesting is perfectly fine:

```javascript
// This is perfectly readable as-is
function greet(name) {
  if (name) {
    return `Hello, ${name}!`;
  }
  return 'Hello, stranger!';
}
```

Early return shines most when you have **three or more preconditions** to check.

## When NOT to Use Early Return

Early return isn't always the answer. Here are cases where I'd think twice.

**Single-expression functions.** If your function is a one-liner, a ternary or null coalesce is simpler:

```javascript
// A guard clause would be overkill here
const getDisplayName = (user) => user?.name ?? 'Anonymous';
```

**Functions with required cleanup.** If you need to release a resource — close a file handle, release a lock, clear a timer — multiple return points make it easy to forget the cleanup. Use `try/finally` to guarantee it runs:

```javascript
function readConfig(path) {
  const handle = openFile(path);
  if (!handle) return null;

  try {
    return parseFile(handle);
  } finally {
    closeFile(handle); // Always runs, even after early return
  }
}
```

**Complex state machines.** When a function has many interacting states rather than simple preconditions, a `switch` statement or a [dispatch table](/blog/dispatch-tables) is often clearer than a chain of early returns.

## Common Mistakes with Early Return

### Forgetting `return` in Express.js

This is the #1 gotcha I see in code reviews:

```javascript
// ❌ Bug: missing return
app.get('/user', async (req, res) => {
  if (!req.user) {
    res.status(401).json({ error: 'Unauthorized' });
    // Execution continues! 💥
  }

  const profile = await getProfile(req.user.id); // Crashes
  res.json(profile);
});
```

`res.json()` does **not** stop function execution. You must add `return`:

```javascript
// ✅ Fixed
if (!req.user) {
  return res.status(401).json({ error: 'Unauthorized' });
}
```

### Over-Guarding

Don't guard against things that can't happen:

```javascript
// ❌ Unnecessary — array.map always returns an array
function formatItems(items) {
  if (!items) return [];
  return items.map(format);
}
```

Only validate at system boundaries (user input, external APIs). Trust your internal code.

## Enforcing Guard Clauses with ESLint

You can configure ESLint to encourage early returns automatically:

```json
{
  "rules": {
    "no-else-return": "warn",
    "max-depth": ["warn", 3]
  }
}
```

`no-else-return` flags unnecessary `else` blocks after a `return`. `max-depth` warns when nesting exceeds 3 levels — a good nudge toward flattening your code with guard clauses.

It's funny how these little patterns sneak up on you. Today's code reminded me that writing for humans — including future me — is just as important as writing for the machine.

## Related

- [Expressions vs Statements](/blog/expressions-statements) - understand the building blocks behind guard clauses and control flow
- [Check if a URL is absolute](/snippets/is-absolute-url) - a concise example of early return for URL validation


Learn the early return pattern (guard clauses) in JavaScript and TypeScript. Reduce nesting, improve readability, and write cleaner functions with real-world examples.

Serhii Shramko

Senior Software Engineer at BetterMe

Featured Posts

Total Build Time Lies

Generic Type Parameters in TypeScript

GraphQL Certified – How I earned my certification

Advanced React

React Re-Renders

Custom Hooks Pitfalls

Elements & Children Props

Projects

Rebookmark

Quizlet QuickList

Udemy Reset Progress

Latest posts

Shiki Class-Based Themes

SEO Audit with AI: 56 Posts, One Afternoon

The early return pattern in JavaScript