
React is continually improving and evolving. React Hooks are a leap forward in how we develop components and manage state in our React applications. Now you can use state and other React features without having to write a class!

Many React developers have switched from classes to React Hooks and are realizing the benefits of understanding their apps better because:

- Related logic is now located together
- Less code is needed compared to the equivalent class
- Function components better align with React’s mental model
- Hooks are just awesome! 🎉

Do you have a codebase filled with class components? You could leave it that way, but it will become increasingly more “legacy” as time continues to pass by. **Why not change now?**

Is your team still not developing with React hooks? The longer you stick with the “old way,” the harder it will be to change when you need to. **Why not change now?**

Hi, I’m Ben Ilegbodu 👋🏾. In this minishop, not only will you learn the ins and outs of React Hooks, but also how to switch to React Hooks from class lifecycle methods, bringing your codebase and your team into the modern React era.

## Get ready to

- Switch from `setState` to the `useState` hook
- Make API calls with the `useEffect` hook instead of the `componentDidMount`, `componentDidUpdate` & `componentWillUnmount` lifecycle class methods
- Create custom hooks to reuse and compose logic
- Use function closures instead of `this` & `.bind` for callbacks and event handlers
- ...and many other features to help you write modern React code

## You’ll need to have

- Prior experience building React applications, specifically using classes
- Experience with modern JavaScript syntax and asynchronous patterns like `Promise` & `async`/`await`

## This minishop may not be for you if you

- Are still new to React (consider the [Zero to React with Hooks](/minishops/zero-to-react-with-hooks/) minishop instead)
- Already have dabbled with React Hooks (consider the [Sharing React Component Logic](/minishops/sharing-react-component-logic/) minishop instead)

## Code of Conduct

By participating in this minishop, you are agreeing to the [Minishop Code of Conduct](/minishops/conduct/).

## What are “minishops”?

Minishops by Ben Ilegbodu are fully-remote workshops that last about 3 hours. They're highly-focused, covering only the concepts you want to learn so that you can level up your skills and get on with the rest of your day. By keeping it short, you’re able to absorb and retain the information before fatigue sets in and other distractions get in your way.

To learn more about minishops, read the [Introducing Minishops](/blog/introducing-minishops/) blog post.

## Questions

If you have questions about the minishop, feel free to email us at [team@benmvp.com](mailto:team@benmvp.com).


Learn how to migrate to React Hooks from classes for a better way to develop components and manage state in React applications

Migrating to React Hooks


React's component-driven design simplifies reusing UI because blocks of markup can be encapsulated into custom components. Likewise, sharing traditional data utilities is straightforward because React is “Just JavaScript”™. But what about when we want to **share stateful logic and behavior** between components while letting them control some or all of the UI?

React has had several approaches over its lifetime to solve this problem:

- Mixins (legacy)
- `as` props
- Higher-order components (HOCs)
- Compound components
- Render props
- Custom hooks

Each pattern has its pros and cons. And even with hooks, there are still **ideal use cases for all of the patterns**.

Hi, I’m Ben Ilegbodu 👋🏾. In this minishop, not only will we learn how to write these patterns for sharing stateful logic, but we will also learn the best situations to apply these patterns in your codebase. You will be able to **replace your unnecessarily complex components** filled with dozens of configuration props and code branches with **powerful components with flexible APIs**.

## Get ready to

- Support **`as` props** for minimal UI flexibility
- Add **render props** to invert UI rendering control
- Create **compound components** to provide layout control
- Leverage **custom hooks** when no shared UI is needed
- ...and many more techniques for creating reusable components

## You’ll need to have

- Experience building React applications with `useState` & `useEffect` hooks
- Experience creating custom hooks
- Experience with advanced hooks like `useContext` & `useCallback` will also be helpful

## This minishop may not be for you if you

- Are still new to React (try the [Zero to React with Hooks](/minishops/zero-to-react-with-hooks/) minishop instead)
- Have React experience, but don’t yet have experience using hooks (consider the [Migrating to React Hooks](/minishops/migrating-to-react-hooks/) minishop instead)

## Code of Conduct

By participating in this minishop, you are agreeing to the [Minishop Code of Conduct](/minishops/conduct/).

## What are “minishops”?

Minishops by Ben Ilegbodu are fully-remote workshops that last about 3 hours. They're highly-focused, covering only the concepts you want to learn so that you can level up your skills and get on with the rest of your day. By keeping it short, you’re able to absorb and retain the information before fatigue sets in and other distractions get in your way.

To learn more about minishops, read the [Introducing Minishops](/blog/introducing-minishops/) blog post.

## Questions

If you have questions about the minishop, feel free to email us at [team@benmvp.com](mailto:team@benmvp.com).


Learn how to write reusable React components using patterns for sharing stateful logic and behavior

Sharing React Component Logic


TypeScript is a JavaScript superset that compiles down to vanilla JavaScript and has become increasingly popular. TypeScript offers strong typing and compile-time verification to our React applications. As a result, using TypeScript helps eliminate entire classes of bugs that commonly affect our apps.

When adopting new tech for development, we should always focus on the impact to the user. The user doesn’t care what tech we use unless it makes their user experience better (less friction, more delightful, etc.). Users definitely do not want a buggy experience, and of course, neither do we.

Hi, I’m Ben Ilegbodu 👋🏾. In this minishop, you will learn how to use TypeScript to build React applications. But instead of simply covering types and syntax, the minishop will have a focus on how using TypeScript can prevent common bugs that infect our applications.

Maybe you’re concerned about the code health of your app and what to learn how **TypeScript can provide confidence** in making big changes. Or maybe your team is building a new React application and you want to see if **TypeScript makes sense** before kicking off the project. Or maybe you’re just questioning whether **TypeScript is worth the learning curve** when you’re already productive building React applications.

Whether these are your reasons or you have others, you’ll no doubt leave convinced that TypeScript will help you in your current or future React projects.

## Get ready to

- Learn basic TypeScript types and syntax
- Define fully type-safe component props
- Type common React hooks
- Handle forms and other events
- ...and many more features that help you write quality code

## You’ll need to have

- No prior experience with TypeScript is necessary! 🙌🏾
- Experience building React applications using hooks (consider taking the [Migrating to React Hooks](/minishops/migrating-to-react-hooks/) or [Zero to React with Hooks](/minishops/zero-to-react-with-hooks/) minishops first)

## This minishop may not be for you if you

- Already have some experience using TypeScript in React (try the [Sharing React Component Logic](/minishops/sharing-react-component-logic/) minishop)
- Have React experience, but don’t yet have experience using hooks (again consider the [Migrating to React Hooks](/minishops/migrating-to-react-hooks/) minishop instead)

## Code of Conduct

By participating in this minishop, you are agreeing to the [Minishop Code of Conduct](/minishops/conduct/).

## What are “minishops”?

Minishops by Ben Ilegbodu are fully-remote workshops that last about 3 hours. They're highly-focused, covering only the concepts you want to learn so that you can level up your skills and get on with the rest of your day. By keeping it short, you’re able to absorb and retain the information before fatigue sets in and other distractions get in your way.

To learn more about minishops, read the [Introducing Minishops](/blog/introducing-minishops/) blog post.

## Questions

If you have questions about the minishop, feel free to email us at [team@benmvp.com](mailto:team@benmvp.com).


Learn how to use strong types with TypeScript in React applications to prevent common bugs that infect our apps

TypeScript for React Developers


React is a JavaScript UI library that makes creating reusable components easy and efficient. It’s critical to understand the fundamentals of creating custom configurable components, fetching and maintaining state, and rendering UI based upon that state and component configurations.

Maybe your team is **taking on a new React project** and you want to get a handle on React development before your kick off the project. Or maybe you are just starting off your development career and want to learn React in order to **increase your job opportunities**. Or maybe you’ve been in the industry for a while, heard so much about React, and finally want to **see what React is all about**.

Whatever the case may be, you’ll leave the minishop with all the fundamentals you need to build your own modern apps with React using hooks.

## Get ready to

- Write configurable, reusable and composable components
- Use JSX syntax
- Work with the “Virtual DOM”
- Handle user interactions and synthetic events
- Maintain application state using hooks
- Make API calls using hooks
- Apply component styling
- ...and many more tidbits and nuances of quality React development

## You’ll need to have

- No prior experience with React is necessary! 🙌🏾
- Experience building web user interfaces with HTML, CSS, and JavaScript DOM APIs
- Experience with modern JavaScript syntax and asynchronous patterns like `Promise` & `async`/`await`

## This minishop may not be for you if you

- Already have experience developing in React with class components (consider the [Migrating to React Hooks](/minishops/migrating-to-react-hooks/) minishop instead)
- Already have dabbled with React Hooks (consider the [Sharing React Component Logic](/minishops/sharing-react-component-logic/) or [TypeScript for React Developers](/minishops/typescript-for-react-developers/) minishops instead)

## Code of Conduct

By participating in this minishop, you are agreeing to the [Minishop Code of Conduct](/minishops/conduct/).

## What are “minishops”?

Minishops by Ben Ilegbodu are fully-remote workshops that last about 3 hours. They're highly-focused, covering only the concepts you want to learn so that you can level up your skills and get on with the rest of your day. By keeping it short, you’re able to absorb and retain the information before fatigue sets in and other distractions get in your way.

To learn more about minishops, read the [Introducing Minishops](/blog/introducing-minishops/) blog post.

## Questions

If you have questions about the minishop, feel free to email us at [team@benmvp.com](mailto:team@benmvp.com).


An introduction to React to learn the critical concepts needed for building modern React applications using hooks

Zero to React with Hooks


There are times in a Jest test when we have a module where the majority of the functions need to be mocked, but we have one (or two) that need to be left alone. Likely in this case most of the functions have side effects. But there are some that are normal input/output (aka "pure") functions that need to work when they are called during a test run. We can use a combination of [`jest.requireActual()`](https://jestjs.io/docs/jest-object#jestrequireactualmodulename) and [`jest.createMockFromModules()`](https://jestjs.io/docs/jest-object#jestcreatemockfrommodulemodulename).

```js
// app.test.js

// create a mock of the `../utils/players` module that is called
// from `app.js` (the code being tested)
jest.mock('../utils/players', () => {
  // use auto-mocking system to get an object that mocks all
  // of the module's functions, just like what `jest.mock()`
  // (w/ no parameters) would do
  const allAutoMocked = jest.createMockFromModule('../utils/players')

  // grab all the *real* implementations of the module's functions
  // in an object
  const actual = jest.requireActual('../utils/players')

  // return a new module implementation
  return {
    __esModules: true,

    // first start with all of the module's functions auto-mocked
    ...allAutoMocked,

    // then optionally include any override module mocks
    getPlayers: jest.fn(() => []),
    getTeams: jest.fn(() => []),

    // lastly override w/ any of the module's functions that
    // we want to use the *real* implementations for
    formatPlayerName: actual.formatPlayerName,
  }
})
```

If you are like how I was looking for how in Jest to mock a JavaScript module to keep the real implementation of one function, but mock the rest, here's your answer! 🎉 Feel free to return to your test code so you can continue writing high-quality tests. 😉 But... if you're interested in learning how all of this works, by all means, read on!

---

[Jest](https://jestjs.io/) has pretty sophisticated mocking utilities, including mocking modules. The [`jest.mock()`](https://jestjs.io/docs/jest-object#jestmockmodulename-factory-options) method allows us to mock a JavaScript module with an auto-mocked version when it is used in a test run.

Let's say we have a `players.js` file with several functions in it.

```js
// players.js

export const getPlayers = (season) => {
  // makes some sort of API call to get all of the players
  // in a given NBA `season`
}

export const writePlayersData = (players, filePath) => {
  // writes `players` data to a JSON file at the
  // specified `filePath`
}

export const getTeams = (playerId) => {
  // makes some sort of API call to get all the teams
  // the specified player has played for
}

export const formatPlayerName = (playerData) => {
  // given the `playerData`, returns a formatted version of
  // their name, including team & jersey number
}
```

And let's say we have an `app.test.js` file, containing tests for `app.js` which uses functions in `players.js`.

```js
// app.test.js

// mock the `../utils/players` module
jest.mock('../utils/players')

// calls to any of the 4 functions in `app.js` will return
// `undefined` because they've been auto-mocked
```

Auto-mocking means that Jest will replace any function within the mocked module (`../utils/players` in this case) with a new function that just returns `undefined`. **So if `app.js` calls `writePlayersData()` during a test run, it'll do nothing instead of writing to the filesystem** (which we probably don't want to do in a unit test).

We can even assert that `writePlayersData` is called in a test by importing it.

```js
// app.test.js

import { run } from './app'
import { writePlayersData } from '../utils/players'

// create a mock of the `../utils/players` module
jest.mock('../utils/players')

// calls to any of the 4 functions in `app.js` will return
// `undefined` because they've been auto-mocked

it('calls `writePlayersData` when the `write` option is true', () => {
  run({ write: true })

  // verify only writing once
  expect(writePlayersData).toHaveBeenCalledTimes(1)

  // verify called with the expected params
  expect(writePlayersData).toHaveBeenCalledWith(/* ... */)
})
```

The `jest.mock()` method also supports parameters that allow us to specify a new implementation for a module instead of the default auto-mocking.

```js
// app.test.js

// create a mock of the `../utils/players` module
// but instead of auto-mocking, provide mock
// implementations
jest.mock('../utils/players', () => {
  // return a new module implementation
  return {
    __esModule: true,

    getPlayers: jest.fn(() => []),
    getTeams: jest.fn(() => []),
    writePlayersData: jest.fn(),
    formatPlayerName: jest.fn(() => ''),
  }
})

// calls to any of the 4 functions in `app.js` during a
// test run will return the mocked values above
```

Now the 4 functions are replaced with the specified mock functions (via [`jest.fn()`](https://jestjs.io/docs/jest-object#jestfnimplementation)) that return mock data. If any of them are called from `app.js` in a test case, the mock functions are used. **These explicit mocks are especially useful for `getPlayers()` and `getTeams()` because they are expected to return data not `undefined` when called.**

There are two problems with this approach. First, even though we're fine with `writePlayersData` being auto-mocked, we still have to include it with the default `jest.fn()`. **Otherwise, `writePlayersData` wouldn't exist at all during a test run.** Second, we have to provide a mock implementation for `formatPlayerName` even though we can (and probably should) use its real implementation.

We can use the [`jest.requireActual()`](https://jestjs.io/docs/jest-object#jestrequireactualmodulename) method to grab the actual implementation of a module instead of a mock.

```js
// app.test.js

// create a mock of the `../utils/players` module
jest.mock('../utils/players', () => {
  // return a new module implementation
  return {
    __esModule: true,

    // spread in the *real* implementations of all the
    // module's functions (especially `formatPlayerName`)
    ...jest.requireActual('../utils/players'),

    // override the following module functions with
    // mock implementations
    getPlayers: jest.fn(() => []),
    getTeams: jest.fn(() => []),
    writePlayersData: jest.fn(),
  }
})

// during a test run, calls to `formatPlayerName()` will be
// normal, but the other 3 will be mocked 👍🏾
```

Using `jest.requireActual()` solves our problem with having to specify a mocked version of `formatPlayerName`. However, our first problem still exists. We still have to specify a default mock for `writePlayersData`. And if the module had more than one function that could be auto-mocked, having to specify them all would be a pain. **It would also be error-prone for when we add or remove functions from the module.**

If we combine `jest.requireActual()` with the [`jest.createMockFromModule()`](https://jestjs.io/docs/jest-object#jestcreatemockfrommodulemodulename) method, we can get the best of both worlds.

```js
// app.test.js

// create a mock of the `../utils/players` module that is called
// from `app.js` (the code being tested)
jest.mock('../utils/players', () => {
  // use auto-mocking system to get an object that mocks all
  // of the module's functions, just like what `jest.mock()`
  // (w/ no parameters) would do
  const allAutoMocked = jest.createMockFromModule('../utils/players')

  // grab all the *real* implementations of the module's functions
  // in an object
  const actual = jest.requireActual('../utils/players')

  // return a new module implementation
  return {
    __esModules: true,

    // first start with all of the module's functions auto-mocked
    ...allAutoMocked,

    // then optionally include any override module mocks
    getPlayers: jest.fn(() => []),
    getTeams: jest.fn(() => []),

    // lastly override w/ any of the module's functions that
    // we want to use the *real* implementations for
    formatPlayerName: actual.formatPlayerName,
  }
})
```

The `jest.createMockFromModule()` method uses the auto-mocking system to generate a mocked version of the module as an object. We use that as our base for the new module implementation (`allAutoMocked`). In our example, this would be for `writePlayersData`, but in a bigger module, this could be for many more functions.

Now since `allAutoMocked` contains all of the auto-mocked functions, we need to override with the ones we care about. We could next provide explicit mocks for `getPlayers` and `getTeams`. More than likely each test case will probably want different implementations for these functions, so in reality we could leave these auto-mocked as well. We would provide implementations in `describe()` blocks below.

Then last, and most importantly, we provide the real implementations of the one (or more) functions we want "un-mocked". **The result is that most of the functions in the module are mocked, and only one or two are using their real implementations.**

---

Like most of my posts, this is a real problem I came across. I had a module where most of the functions had side effects so they needed to be auto-mocked in my tests. But I had one "pure" function that I absolutely could not mock because it was necessary for the code to run.

I found [one answer on StackOverflow](https://stackoverflow.com/a/58607108) written back in October 2019 that created `allAutoMocked` using `jest.requireActual` but replacing the values with `jest.fn()`. That _was_ my implementation until PR feedback pointed me to `jest.createMockFromModule()`. It was introduced somewhat recently in [Jest 26](https://jestjs.io/blog/2020/05/05/jest-26) (May 5, 2020) so I didn't even know about it. Obviously, it didn't exist when the StackOverflow answer was written either.

My hope is that this post saves somebody from multiple hours of searching for a reasonable answer. 😃 But if you've got any questions about this problem or other JavaScript testing questions, feel free to reach out to me on Twitter at [@benmvp](https://twitter.com/benmvp).

Keep learning my friends. 🤓


A shorthand way with jest.mock() to auto-mock all functions in a JavaScript module yet use the real implementation of one function

Mock all functions in a JavaScript module except one using Jest


I use [`semantic-release`](https://github.com/semantic-release/semantic-release) for both personal and work projects to automate version management and publishing of packages. It's nice because it takes care of the entire release flow, like figuring out the [next version](https://docs.npmjs.com/cli/v8/commands/npm-version) (using [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format)), auto-generating GitHub release notes, and finally [publishing the package](https://docs.npmjs.com/cli/v8/commands/npm-publish) to the npm registry.

I like `semantic-release` for the handful of personal projects I work on because package publishing is a part of DivOps that I don't want to deal with. Developing the library is enough. 😃 At work `semantic-release` **provides a centralized point in CI that handles releasing a package** so that individual developers aren't trying to figure it out on their machines.

The default `semantic-release` configuration does all that I described, so initially I could release without an explicit config. Then I use [npx](https://www.npmjs.com/package/npx) to run it in CI. For example, a `release.yml` [Github workflow](https://github.com/features/actions):

```yml
name: Release

on: push

jobs:
  main:
    name: NPM Release
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Use Node v16
        uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Run unit tests
        run: npm test
        env:
          CI: true

      - name: Run integration tests
        run: npm run integrate
        env:
          CI: true

      - name: Release new version to NPM
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        # highlight-next-line
        run: npx semantic-release
```

> I don't even install `semantic-release` as a dependency in the project. I always use the latest version.

However, sadly the default configuration [still uses `master` as the default branch](https://github.com/semantic-release/semantic-release/issues/1581). Since all of my repos use `main` as the default branch, I now need a `release.config.js` to configure the [supported branches](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#branches).

```js {3}
module.exports = {
  branches: [
    'main',
    'next',
    'next-major',
    // version number branches will release that version
    '+([0-9])?(.{+([0-9]),x}).x',
    { name: 'beta', prerelease: true },
    { name: 'alpha', prerelease: true },
  ],
}
```

And because all of my libs are written in TypeScript, I also have a build step before releasing the pacakge. The build step allows the project to transpile TypeScript into vanilla JavaScript and auto-generate TypeScript declaration files (`*.d.ts`). As a result, **I need to specifically configure the [`@semantic-release/npm` plugin](https://github.com/semantic-release/npm) to specify the build directory (typically `lib/` for me)**. But to configure the plugin, I also must include all of the [plugins](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#plugins) used by default.

```js {19-21}
module.exports = {
  branches: [
    'main',
    'next',
    'next-major',
    '+([0-9])?(.{+([0-9]),x}).x',
    { name: 'beta', prerelease: true },
    { name: 'alpha', prerelease: true },
  ],

  plugins: [
    // analyzes commits w/ conventional-changelog
    '@semantic-release/commit-analyzer',

    // generates a changelog w/ conventional-changelog
    '@semantic-release/release-notes-generator',

    // publishes the npm package from the specified folder
    ['@semantic-release/npm', {
      pkgRoot: './lib'
    }]

    // Publishes changelog as a GitHub release and
    // comments on released Pull Requests & Issues
    '@semantic-release/github',
  ],
}
```

> FYI: at work I also use [`semantic-release-slack-bot`](https://github.com/juliuscc/semantic-release-slack-bot) to get release notifications in Slack from a Slack bot, but I'm leaving it out to simplify the discussion.

With the addition of the build step, the `release.yml` Github workflow now looks like:

```yml
name: Release

on: push

jobs:
  main:
    name: NPM Release
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Use Node v16
        uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Run unit tests
        run: npm test
        env:
          CI: true

      - name: Run integration tests
        run: npm run integrate
        env:
          CI: true

      # highlight-start
      - name: Build package
        run: npm run build
      # highlight-end

      - name: Release new version to NPM
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release
```

Because `semantic-release` relies on a strict commit format (by default [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format)) in order to auto-determine the next version, **I also set up all of my GitHub projects to only support [squash merge commits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) in Pull Requests**. I've found that it's the least painful way to ensure developers use the proper commit format because I also add another GitHub workflow to validate the Pull Request title using the [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request) GitHub action. An example `validate-pr.yml` workflow file looks like:

```yml
name: Pull Request

on:
  pull_request_target:
    types:
      - opened
      - edited
      - synchronize

jobs:
  main:
    name: Validate PR title
    runs-on: ubuntu-latest
    steps:
      ## highlight-next-line
      - uses: amannn/action-semantic-pull-request@v4
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

---

## Supporting one-off releases

**When working on a library project, at times I need to test how it'll work in a host application before merging a Pull Request.** There are some features that automated tests just cannot cover. They are best verified by using the library in a host app. We need to add a "dev" version of the package as a dependency in the app, just like we would for a real released version. But how exactly do we do that?

Back in the day I would use [`npm link`](https://docs.npmjs.com/cli/v8/commands/npm-link) to symlink the dependency in the app's `node_modules` to the library project folder. But that stopped working once I started transpiling code and the project folder looked different than the package folder. This difference is also why using a GitHub project reference also doesn't work.

So on a library that I develop solely by myself, I would run [`npm pack`](https://docs.npmjs.com/cli/v8/commands/npm-pack) locally to create a tarball (`.tgz`) of the package. An app's `package.json` can [install](https://docs.npmjs.com/cli/v8/commands/npm-install) a tarball from a local path instead of a version in the registry. So I would `npm pack` the package, put it somewhere on the filesystem, and reference it in my test app's `package.json`. But that's not an easily repeatable pattern for multiple devs on a team, especially when some are infrequently contributing to the lib.

So when on a team, **I initially ab-used the `alpha` pre-release branch.** When someone on the team needed to test a release, they merged their (properly-titled) commits into the project's `alpha` branch. And when they pushed it to `origin`, the `release.yml` workflow would run. And since `alpha` is listed in the `branches` of the `release.config.js` as a pre-release, the new code would release at a new alpha version.

This approach worked okay. The `alpha` branch ended up having a lot of trial and error code. But as long as we merged `main` into it regularly, it cleaned up pretty well. **However, when we had multiple developers who wanted to test their dev branches with `alpha` releases simultaneously, we ran into trouble.** We had to get the "all clear" to release alphas in serial. And since we could have multiple dev branches merging into alpha sequentially, the branch itself could get into a pretty gnarly state.

We need to isolate the dev branches into their releases. We need something akin to running `npm pack` locally, but with the consistency that running `semantic-release` in CI provides. **So what we can do is add another pre-release branch, but use a pattern for multiple branch support.**

```js {10-12}
module.exports = {
  branches: [
    'main',
    'next',
    'next-major',
    '+([0-9])?(.{+([0-9]),x}).x',
    { name: 'beta', prerelease: true },
    { name: 'alpha', prerelease: true },

    // Any branch starting with `test-` will be auto-released
    // as a pre-release (e.g. `1.3.0-test-add-cool-new-feature.1`)
    { name: 'test-*' prerelease: true},
  ],

  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/npm', {
      pkgRoot: './lib'
    }]
    '@semantic-release/github',
  ],
}
```

Let me break down how I can release a new "dev" version for my PR branch.

1. I do my dev work on a branch named `add-cool-new-feature`
1. I merge the (properly-titled) commits into a `test-add-cool-new-feature` branch (creating it if this is the first time)
1. I push `test-add-cool-new-feature` to `origin`
1. CI runs and releases the one-off version (e.g. `1.3.0-test-add-cool-new-feature.1`)

Instead of including "alpha" or "beta" in the version, it includes the entire name of the branch. If I continue to push new commits to the branch the `.1` part will be `.2`, `.3`, etc. **And now I can create my test release branches while other developers can do the same in parallel.** And once we're done, we delete our branches from `origin`. The `alpha` and `beta` [pre-release branches](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases) remain as they should be.

---

Well, hopefully, this example helps you out! The configuration for `semantic-release` itself is surprisingly uncomplicated. It's just an additional entry in the `branches` config. But I think what's most interesting is the concept itself. Even though `semantic-release` has a pretty strict commit syntax which enables it to publish a real versioned release on every commit, we can still configure it to act like our old strategies from before.

I would love it if you could let me know if you found this post helpful. Feel free to reach out to me on Twitter with comments or questions at [@benmvp](https://twitter.com/benmvp).

Keep learning my friends. 🤓


How to configure semantic-release to release one-off test branches in an app in order to test dev code prior to merging a Pull Request

Create one-off releases with semantic-release


When developing Next.js apps I want to be able to include other files within the `src/pages` directory besides the [page React components](https://nextjs.org/docs/basic-features/pages) or [API routes](https://nextjs.org/docs/api-routes/introduction). I'm perfectly fine putting components in `src/components` and helper functions in `src/utils`. But I like to co-locate other files with my pages and API routes.

Instead of creating a parallel `__tests__` folder, I like putting my `*.test.ts` or `*.test.tsx` [Jest unit tests](https://jestjs.io/) next to whatever it is that I'm testing. That works great in `src/components`, `src/utils` or any other location outside of `src/pages`. Similarly, I like putting my [Storybook stories](https://storybook.js.org/) (`*.stories.tsx`) next to my React components, including my page components (made possible by [Storybook Addon Next Router](https://storybook.js.org/addons/storybook-addon-next-router)).

But when I add these files within `src/pages` or `src/pages/api` and run `next build`, I get the following error:

```text
Build error occurred

Error: Build optimization failed: found page without a
React Component as default export in

pages/my/plan.stories

See https://nextjs.org/docs/messages/page-without-valid-component
for more info.
```

It's pretty nice that the error leads me to a place where I can find more info. I love when frameworks do this. But when I visit the [Page Without Valid React Component](https://nextjs.org/docs/messages/page-without-valid-component) page it gives a rather short explanation as to why the error ocurred, and some possible ways to fix it. The problem is that all the possible ways to fix it assume I somehow screwed up! 😢

I mean I guess I did screw up by putting other files in the `src/pages` folder, but it seems like something that should be allowed! Why is Next.js so picky about what files go in there? I guess since Next uses [page-based routing](https://nextjs.org/docs/basic-features/pages) it makes sense that it will have no way of interpreting page component files from test files or Storybook stories.

So for the longest I just accepted my fate and put my stories in a sibling `src/page-stories` directory and just avoided writing unit tests, moving nearly everything into `src/utils`. But it felt a bit clunky.

Then a coworker showed me a workaround! The [`pageExtensions` configuration](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions) allows us to alter the default list of valid page extensions (`.tsx`, `.ts`, `.jsx`, and `.js`). The config option is aimed at tools like [`@next/mdx`](https://github.com/vercel/next.js/tree/canary/packages/next-mdx), which have files that end in `.mdx`. But we can take advantage of it to let us put non-page files in the `src/pages` folder as well. And it's right there in the [docs](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions#including-non-page-files-in-the-pages-directory).

We add special extensions for the page components and API routes to help Next.js distinguish them from all of the other files.

```js
module.exports = {
  pageExtensions: [
    // `.page.tsx` for page components
    'page.tsx',
    // `.api.ts` for API routes
    'api.ts',
  ],
}
```

Because I exclusively develop in TypeScript, I only have TypeScript extensions. So all of my pages end in `.page.tsx`, such as `src/pages/my/plan.page.tsx`. And any of my API routes end in `.api.ts`, such as `src/pages/api/client/auth.api.ts`. I give the API routes their own extension, just for added clarity. And because page components will always have JSX, there's no need for `.page.ts`. Likewise, since API routes should never have JSX, there's no need for `.api.tsx`.

Now I can have `plan.page.tsx`, `plan.test.tsx` and `plan.stories.tsx` all in the same `src/pages/my` folder! And the cool thing is if I want to add a `utils.ts` or `constants.ts` in the `src/pages` folder, it will also work. Who knew something so simple could be so exciting? 😂

Keep in mind, though, that this change also has to apply to any [Custom App](https://nextjs.org/docs/advanced-features/custom-app) (`src/pages/_app.tsx`), [Custom Document](https://nextjs.org/docs/advanced-features/custom-document) (`src/pages/_document.tsx`), and [Custom Error Pages](https://nextjs.org/docs/advanced-features/custom-error-page) (`src/pages/404.tsx` & `src/pages/500.tsx`) that we've defined. They'll all need the `.pages.tsx` extension.

---

While I'd love for everyone to find my blog post to get their answer, the [Page Without Valid React Component](https://nextjs.org/docs/messages/page-without-valid-component) error page is _slightly_ more discoverable. 😅 So I submitted a [pull request](https://github.com/vercel/next.js/pull/34285) to add a link to the [Custom Page Extensions](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions#including-non-page-files-in-the-pages-directory) page. As of writing, there are [194 open pull requests](https://github.com/vercel/next.js/pulls) on the [Next.js repo](https://github.com/vercel/next.js). So it may take a while to merge, if ever. Until then, I'll rake in the page views! 🤣

If you've got any questions or suggestions, feel free to reach out to me on Twitter at [@benmvp](https://twitter.com/benmvp).

Keep learning my friends. 🤓


How to include test and other non-page files next to page components and API routes within the pages directory in a Next.js application

Putting test files in the pages folder in a Next.js app

A journey explaining how digging into 3rd-party code helped provide clarity & find a workaround to a tricky problem

Avoiding React act warning when accessibility testing next/link with jest-axe


I was recently working on a React component in a shared component library. The component library up until recently had only been used in client-side rendered apps (think [Create React App](https://create-react-app.dev/)). However, once it started being used in server-sie rendered apps (think [Next.js](https://nextjs.org/)), I started getting the React server hydration mismatch error. For prop errors, the warning looks something like:

```text
Warning: Prop `className` did not match. Server: "positive" Client: "zero"
```

or for text content:

```text
Warning: Text content did not match. Server: "0" Client: "5"
```

Unlike most React warnings, this warning doesn't link to a doc explaining the warning in greater details with some suggested solutions (like for instance the [Invalid Hook Call Warning](https://reactjs.org/warnings/invalid-hook-call-warning.html)). There _are_ docs on the [`hydrate()`](https://reactjs.org/docs/react-dom.html#hydrate) function that does the client-side hydrating on a server-rendered app, but we'd have to know to find it.

Let's walk through what's happening in my component. Here is a representation of the code:

```js
const Incrementer = () => {
  // initialize the state from a value in `localStorage`
  // if it exists
  const [value, setValue] = useState(() => {
    // using lazy state initialization so that we only
    // read from `localStorage` the very first render
    let initValue

    // test for the presence of `window` because it
    // won't exist in Node for server-side rendering.
    // we'll only get the `localStorage` value in
    // the browser
    if (typeof window === 'object') {
      initValue = window.localStorage.getItem('value')
    }

    return initValue ? parseInt(initValue, 10) : 0
  })
  let className = 'zero'

  if (value < 0) {
    className = 'negative'
  } else if (value > 0) {
    className = 'positive'
  }

  return (
    <div className={className}>
      <button onClick={() => setValue((curValue) => curValue - 1)}>-</button>
      <span>{value}</span>
      <button onClick={() => setValue((curValue) => curValue + 1)}>+</button>
    </div>
  )
}
```

> FYI: This is not the **actual** code in the component library. The actual code is a `useMedia()` Hook for tracking the match state of a media query in Javascript. That code is quite involved, so I've simplified it with this example.

The component is a very standard minimal example that's used to show interactivity in a React component. The only difference is that it optionally retrieves its initial value from [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) using [lazy state initialization](https://reactjs.org/docs/hooks-reference.html#lazy-initial-state). If you don't know what lazy state initialization is or when you should use it, check out a previous post of mine called [Four characters can optimize your React component](https://www.benmvp.com/blog/four-characters-optimize-react-component/).

**Because `window` doesn't exist in the Node environment during server-side rendering, the component first has to check if `window` exists before accessing `localStorage`.** Therefore, when the component is rendered server-side, `value` will always be `0`, the default value (`className` will also be `"zero"`). And when the component renders on the client-side, `window` will exist, and it can read from `localStorage` to get the initial value.

The fact that React components can render server-side is pretty cool. But unfortunately this code doesn't quite work as expected. The server-side render actually works fine with the default `0` value. Also, if the component was only rendered client-side, the component renders fine as well (reading from `localStorage` if the stored value exists). But it's when the component is _hydrating_ on the client from server rendered HTML that we have a problem. **React expects the initial render on the client to match what was rendered on the server.** To get a better understanding of hydration, read [Josh W. Comeau](https://twitter.com/joshwcomeau)'s blog post, [The Perils of Rehydration](https://www.joshwcomeau.com/react/the-perils-of-rehydration/#two-pass-rendering).

But if the component gets a value from `localStorage` (let's say `"15"`) with the initialization of state, both `value` (`15`) and `className` (`"positive"`) will be different than the default values (`0` and `"zero"`) rendered on the server. And when what is hydrated on the client differs from what was server-rendered, we get the server hydration error.

```text
Warning: Text content did not match. Server: "0" Client: "15"
```

And the real error isn't actually the warning. The real problem is that our UI is "stale." **React doesn't update the UI to match the props that were rendered differently by the client during hydration.** Instead it keeps the attributes that were already in the markup from the server-side rendering. React _does_ update the text content, however. So in our example, `15` will be rendered in the `<span>`. But because it does _not_ update props, the `className` will still be `"zero"` (instead of `"positive"`).

---

## Typical fix

The typical fix for this is to move all of the `localStorage` stuff into the [`useEffect()`](https://reactjs.org/docs/hooks-effect.html) Hook. That's what it's for; a place that we can safely access the DOM (including `window`) that has no impact on server-side rendering. The fixed code would now look something like:

```js
const Incrementer = () => {
  // always initialize the state to `0`
  const [value, setValue] = useState(0)
  let className = 'zero'

  if (value < 0) {
    className = 'negative'
  } else if (value > 0) {
    className = 'positive'
  }

  useEffect(() => {
    // once we've hydrated on the client w/ the initial
    // render, check to see if we have a value stored
    // in `localStorage`. if so, update `value`. this
    // will result in a second render.
    // (no need to check for existence of `window` cuz
    // it's guaranteed to be there)
    const storedValue = window.localStorage.getItem('value')

    if (storedValue) {
      setValue(parseInt(storedValue, 10))
    }
  }, [])

  return (
    <div className={className}>
      <button onClick={() => setValue((curValue) => curValue - 1)}>-</button>
      <span>{value}</span>
      <button onClick={() => setValue((curValue) => curValue + 1)}>+</button>
    </div>
  )
}
```

> NOTE: Apps using a CSS-in-JS library (such as [emotion](https://emotion.sh/docs/introduction)) also run into this warning with mismatched `className` props. But the issue isn't that the component is accessing APIs only available in the browser. The problem is that the server-side render doesn't contain the final `className` that is generated on the client. Most CSS-in-JS libraries have a guide for solving this problem (for example [emotion's Server-side rendering guide](https://emotion.sh/docs/ssr)).

Our warning is gone and our UI is correct!

Now instead of conditionally initializing the `value` state based on whether or not `window` exists and whether or not there's a value stored in `localStorage`, we just always initialize the `value` state to the default `0`. The server-side render remains the same, rendering `0` and `"zero"`. And the client-side hydration on the initial render also renders `0` and `"zero"`.

But then after the initial render, the `useEffect()` Hook kicks in and runs the effect. That is when we read `localStorage` if it exists and update the `value` state. Calling `setValue` causes the component to re-render with the new value. So now `value` will be `15` and `className` will be `"positive"`. Our UI now looks good. 👍🏾

**The drawback with this fix is that it requires 2-pass rendering on the client.** The first pass at hydration matches the server-side rendering, and the second pass after `useEffect()` is based on the `localStorage` information. There's no real way to avoid this dual rendering with sever-side rendering (yet).

However, when this component is rendered in client-side only apps, it still does the 2-pass rendering. There's no hydration from server rendering happening, so there's no need for the initial render to use the default values. **Ideally, as an optimization, the initial render will read from `localStorage`** (which it can do because we're only rendering in the browser) and render the very first time with the correct data. This is basically what the initial code was doing. That original code works great for client-side only apps, but as we've seen breaks with server-side rendered apps.

**Remember, this component can exist in either client-side only apps or server-side rendered apps.** And since it was still be used throughout lots of client-side only apps, I didn't want to add that extra render to all of these apps.

---

## Ideal fix

**The ideal fix would be for us to determine from React that the initial render of the component is actually the hydration render.** Something that would tell us that this rendering is a result of the app calling [`ReactDOM.hydrate()`](https://reactjs.org/docs/react-dom.html#hydrate) versus [`ReactDOM.render()`](https://reactjs.org/docs/react-dom.html#render). That way if the component is rendering on the server or hydrating from the server, we'll use the default values and do 2-pass rendering. Otherwise, we'll know we're only client-side rendering and can optimize to single-pass rendering.

In all my googling, I did find Github links to some React internals that I could import to know if the component was in the hydration phase. **But I avoid importing React internals at all cost.** The Github link was for React 16, so no doubt it changed with React 17. I didn't even bother to look because I knew that wasn't the route I wanted to go.

---

## Workaround fix

So since I couldn't realistically find out from React if it was hydrating, I did the next best thing: used a global variable 😭.

```js
// helper to read the `localStorage` value and parse to an
// integer, if it exists
const getLocalStorageValue = () => {
  const storedValue = window.localStorage.getItem('value')

  return storedValue ? parseInt(storedValue, 10) : undefined
}

const Incrementer = () => {
  // initialize the state from a value in `localStorage`
  // if it exists and not hydrating
  const [value, setValue] = useState(() => {
    // using lazy state initialization so that we only
    // read from `localStorage` the very first render
    let initValue

    // in addition to testing for `window` we also check
    // if the app wasn't server-side rendered. when it
    // wasn't, it's safe to get the `localStorage` value
    // early here in state initialization
    if (typeof window === 'object' && !window.__WAS_SSR) {
      initValue = getLocalStorageValue()
    }

    return initValue || 0
  })
  let className = 'zero'

  if (value < 0) {
    className = 'negative'
  } else if (value > 0) {
    className = 'positive'
  }

  useEffect(() => {
    // if the app wasn't server-side rendered, `value`
    // already is the `localStorage` value, so getting and
    // setting it again won't cause a re-render. however,
    // if the app was server-side rendered, `value` is the
    // default so we need to now get the value from
    // `localStorage` and set it
    const storedValue = getLocalStorageValue()

    if (storedValue) {
      setValue(storedValue)
    }
  }, [])

  return (
    <div className={className}>
      <button onClick={() => setValue((curValue) => curValue - 1)}>-</button>
      <span>{value}</span>
      <button onClick={() => setValue((curValue) => curValue + 1)}>+</button>
    </div>
  )
}
```

The code is basically a hybrid of the original solution (optimized, but broken) and the second solution (sometimes inefficient, but always accurate). **Now we have a solution that is always accurate, and efficient for client-side only renders as well.**

The state initialization is almost the same as the original code except it also checks against the `window.__WAS_SSR` property ("was server-side rendered") set by the app. If the app said that it wasn't server-side rendered or didn't set the global property at all, then the component will do the optimized single-pass render by reading the `localStorage` in the state initialization. **The assumption is that if the app says that it wasn't server-side rendered, there's no hydrating going to happen.** The `useEffect()` Hook still runs, but doesn't cause a second render because the `value` will be the same.

However, if the `window.__WAS_SSR` property is set to `true` by the app, then on the client the first render is hydration. So then the state initialization will return the default value to match the server-side render. It's when the `useEffect()` Hook executes that the real value is set. This is the 2-pass solution.

Although the component doesn't know if it's being rendered in a client-side only app or a server-side rendered app, **the app itself does know how it's being rendered.** So a server-side rendered app can set the `window` value in module scope in the top-most component.

```js
// in App.js (or equivalent)

import React from 'react'
// other imports as needed

if (typeof window === 'object') {
  // mark that the app was server-side rendered
  window.__WAS_SSR = true
}

const App = () => {
  // render the app
}

export default App
```

> For my Next.js projects, I set this in the [custom `App`](https://nextjs.org/docs/advanced-features/custom-app) (`pages/_app.js`).

I use the `window` object because it will only exist in the browser, which is where hydration will happen.

One thing to note is that **this solution biases towards client-side only apps**. If the `window.__WAS_SSR` property is not set, it'll do the optimized single-pass render by default. This means that any server-side rendered app will be broken by default without the `window` property. I could've named the property something like `window.__NO_SSR` so that the component by default would do 2-pass rendering. And only if the property is set will it do the optimized 1-pass rendering.

I chose my approach because the vast majority of the apps consuming the React component library are still client-side only and I didn't want to have to go update them all. It was much easier to update the 1 or 2 new server-side rendered app.

---

## Theming fix

As I mentioned earlier, this `Incrementer` component is a simplification of my actual code, a `useMedia()` custom Hook. Although I wasn't thrilled with the global variable approach, I felt a bit validated because [MUI](https://mui.com/) (my go-to React UI library) has its own `useMediaQuery()` Hook that takes a similar global approach.

The Hook has the same problem of being used in both client-side only and server-side rendered apps, without knowing which environment it's in. **But instead of resorting to a global variable like I did, they [made use of their theming engine](https://github.com/mui-org/material-ui/blob/505cf9e7a181d603e22b604fd8de1ab926a018cc/packages/mui-material/src/useMediaQuery/useMediaQuery.ts#L44-L49)** which is a much more robust global UI data store. So when the app sets up the primary and secondary colors, it can also set the [`noSsr`](https://mui.com/components/use-media-query/#client-side-only-rendering) property for MUI to only do the single-pass rendering.

If my component library provides theming in the future, I'll definitely switch to this approach!

---

Phew! That was a lot of information. 😅 The code itself isn't really all that complicated. It's just that React hydration and its ramifications aren't really well-known. So we really have to understand the problem first in order for the solution to make sense.

I still want to see what I can do about the 2-pass solution for server-side rendered apps. The result is that the user sees the component with the default value values, and some time later with the up-to-date values. Depending on what's being rendered and the user's internet connection, the switch over can be slow and jarring (or fast and hardly noticeable). I'm not sure what the solution will be, but I will share another post if/when I have something.

Keep learning my friends. 🤓


How to resolve the server mismatch error when hydrating a shared React component that can be used in client-side only or server-side rendered apps

Handling the React server hydration mismatch error


I was recently working on my latest project, which uses [Firestore](https://firebase.google.com/) as its NoSQL database. The way the data is stored in Firestore is _almost_ how I represent the data in app. The only difference is that Firestore has its own object for modeling dates that is different than the JavaScript [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object. So in order to avoid having to write almost identical types for both the internal and Firestore representations of an object (and keep them in sync over time), I created a generic TypeScript utility type that would recursively replace all `Date` types to Firebase [`Timestamp`](https://github.com/firebase/firebase-js-sdk/blob/2e7586dd7320d48d4b58aa13b525ec4a599f87e2/packages/firestore/src/lite-api/timestamp.ts) types in any type whether it's an interface, array or something else.

```typescript
// A generic type that returns a new type by returning a
// `Timestamp` if the generic parameter is a `Date`.
// Or, if given an array type, it returns the same
// array type except replacing the item `Date` types w/
// `Timestamp` types. Does the same for object value
// types as well. Otherwise, just returns the type back.
type ToFirestore<MaybeDate> = MaybeDate extends Date
  ? Timestamp
  : MaybeDate extends Array<infer Item>
  ? Array<ToFirestore<Item>>
  : MaybeDate extends Record<string, any>
  ? { [Key in keyof MaybeDate]: ToFirestore<MaybeDate[Key]> }
  : MaybeDate
```

> See the code in action on the [TS Playground](https://www.typescriptlang.org/play?#code/PTAEFkHsGMGtQE4FMAOyDOSB2AXAhjgJaRaiQBmoeoAYoRjpMqAAYAqhAtkuvpyi1A4AniiQAoQriQJyeaElAduvPP1ABvcaB2IkeACYkANsNCZoJA+gBcoLAFdOAIxkAabbuSGTZrHixICytbeydXBHEAX3FxEFAAQVAAc2wZQmghUUUcAAsCPRwHBCx0KnskAHcssVBnM2Qikqlkqjiwdi4ePgFQQko8xVSsdMyUPAQ1JBwZPrLqFgARAiQWADp20AB5BDc+ymTCADdsKlIJybMRMT3CHELi0qFcxXQpzYu8K+zQJAAPBQoe7IFDGeQtZ6KO5ITisZYzQTXHigSrATadFQ9RHZdBrUCLSDIwbmKagchMMjOABWSGg9yOeGMDgk8SR8zKlSQxmMeK2gwQlUImD2VIcvAeJTKxKRdXksA2MrYkDoDCYSAAPOAvq54UgAHygAC8EG1SF1vz+Myw1nxK08AH4lF1VPxPHYtcIdSsLVabQkEJd1VJyLMAJIzTh6h2JANfdVKlXdNXq8MwvVRnTu03m-6+soAJVpTAM6t4CBaewCwgzoEdGlAAG0ANJIMxSUCwVsUE2es0rAC6dgT9CTyE12ZWzdb-YNMUzPa9M1iUhmsnkigACmDSFodJZuXhnEwCExQmWWg3+55oN4ZgY7LrPAYudMkAZ7Q+7TpCPfzDhy1gySeNwjKhLuuigAYKyfkuEHIOQdjnoBng6EidgAOTON4sByLw6GgAAPqAmEIA4WDQLk+FEehTLkZRhHEQYUgjAgVHEeg-hwOhnhRJeniqEUoToWx6FoFwEzCCJEwUccb7cTonCQEx5CEG+MESDo-jcIh-4tJ4kCVCxOkAUBOhHEKhDOIQxh3MIGFiQyMwiTZWCwAAtL4IkoA4zg2dA3ExJsAASkAnAgZBhawia8GqW4BIikDmEgUI4GUz4qVgdzEKQgp5OiyjdGovRsn0pCguuZCUEsKzYmI6DiDK0WMMgcWkMaw6qmOrVRg1PxIkk7XKiOMVjkhyRRjKSIAEJGkoQ2dRqjguDIl4TX12QAMKzR1o4avWWlIMZFZUKkdhLREoBRFGQA).

This post is the third post in a series on TypeScript generics. The first post introduced generics by [re-implementing lodash functions](/blog/understanding-typescript-generics-lodash-functions/). In the second post, we [learned TypeScript generics by rebuilding existing utility types](/blog/learn-typescript-generics-rebuilding-existing-utility-types/). Now in this final post we're creating our own custom generic utility types using everything we've learned.

---

**`ToFirestore<>` is a recursive conditional generic type expression.** 😅 To make things even more complex, it has 3 levels of conditional nesting so that it can all be a single expression. Its goal is to take a type and convert any `Date` types to `Timestamp` types. So if the generic parameter is a `Date` type itself, return a `Timestamp` type instead. If it's an array type, turn any `Date` array element types to `Timestamp` array element types. If it's an object type, convert any `Date` property value types to `Timestamp` property value types. And if it's none of the above, just return the type back because there's nothing to convert.

Let's break it down line by line.

```typescript
// When `MaybeDate` is a `Date` type, it returns a
// `Timestamp` instead
// highlight-range{1-2}
type ToFirestore<MaybeDate> = MaybeDate extends Date
  ? Timestamp
  : MaybeDate extends Array<infer Item>
  ? Array<ToFirestore<Item>>
  : MaybeDate extends Record<string, any>
  ? { [Key in keyof MaybeDate]: ToFirestore<MaybeDate[Key]> }
  : MaybeDate

type TypeA = ToFirestore<Date>
// ⮑ Timestamp

type TypeB = ToFirestore<Date | boolean>
// ⮑ Timestamp | boolean
```

`ToFirestore<>` takes a single type parameter, `MaybeDate`. **If `MaybeDate` is a `Date` type, then the "true" branch of the conditional returns a Firebase `Timestamp` type instead.** This is the base case of the recursive type and serves as the crux of the mapping of an object with `Date` types to an object of Firebase `Timestamp` types.

```typescript
// When the generic `MaybeDate` is an array, we convert all of
// the `Date` types in the array type to `Timestamp` types
// by recursively calling `ToFirestore<>` on the item types
// (the `infer` keyword creates a new generic type called
// `Item` which represents the type of the array items)
// highlight-range{3-4}
type ToFirestore<MaybeDate> = MaybeDate extends Date
  ? Timestamp
  : MaybeDate extends Array<infer Item>
  ? Array<ToFirestore<Item>>
  : MaybeDate extends Record<string, any>
  ? { [Key in keyof MaybeDate]: ToFirestore<MaybeDate[Key]> }
  : MaybeDate

type TypeA = ToFirestore<Date[]>
// ⮑ Timestamp[]

type TypeB = ToFirestore<(Date | string)[]>
// ⮑ (Timestamp | string)[]

type typeC = ToFirestore<number[]>
// ⮑ number[]
```

Now, we're in the "false" branch of the outermost conditional, which in fact starts a new, nested generic conditional type. It looks like our typical conditional, except for the [`infer`](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#inferring-within-conditional-types) keyword. **Not only are we testing to see if `MaybeDate` is an `Array<>` type, but if it is, we also get a new generic type (called `Item` here) that we can use in the nested "true" branch.** `Item` is the type of the array items.

The "true" branch of the nested conditional converts the array item types to `Timestamp` types if the array item types are `Date` types (or include `Date` types in a union). **We make use of the auto-created `Item` generic from the `infer` keyword to recursively pass the array item type to a recursive call `ToFirestore<>`.** So `ToFirstore<Date[]>`, returns `Timestamp[]`. But also, if we pass an array of types that union with a `Date` (such as a `ToFirestore<(Date | string)[]>`), we'll get back an array with a union of types as well, except the `Date` has been replaced by `Timestamp`.

> `ToFirestore<>` is recursive because it calls itself. It allows us to take a type with an arbitrarily deep structure, and convert all the `Date` types to `Timestamp` types.

But let's continue on to the nested "false" branch that now starts yet another nested conditional (we're on our third one now 😅).

```typescript
// If the generic `MaybeDate` is not a `Date` nor array type,
// check if it's an object type by seeing if it extends
// `Record<string, any>`. And if so, create a new object type
// with the same keys, converting any `Date` value types to
// `Timestamp` value types by recursively calling `ToFirestore<>`
// on the value types
// highlight-range{5-6}
type ToFirestore<MaybeDate> = MaybeDate extends Date
  ? Timestamp
  : MaybeDate extends Array<infer Item>
  ? Array<ToFirestore<Item>>
  : MaybeDate extends Record<string, any>
  ? { [Key in keyof MaybeDate]: ToFirestore<MaybeDate[Key]> }
  : MaybeDate

type TypeA = ToFirestore<{ name: string; birthDate: Date }>
// ⮑ { name: string, birthDate: Timestamp }

type TypeB = ToFirestore<{ id: number; created: Date; dates: Date[] }>
// ⮑ { id: number, created: Timestamp, dates: Timestamp[] }

type TypeC = ToFirestore<{ from: Date; to: Date }[]>
// ⮑ { from: Timestamp, to: Timestamp }[]

type TypeD = ToFirestore<{
  name: string
  players: { fullName: string; birthDate: Date }[]
}>
// ⮑ {
//  name: string,
//  players: { fullName: string, birthDate: Timestamp }[]
// }

type typeE = ToFirestore<{ name: string; age: number }>
// ⮑ { name: string, age: number }
```

If the `MaybeDate` is not a `Date` nor an array, we next want to see if it's an object type instead. We do that using another conditional to see if the `MaybeDate` extends `Record<string, any>`, a base object literal type. **The "true" branch of the doubly nested conditional takes an object type and using [mapped types](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html) converts it to a new object type with the same key types.** Using `ToFirestore<>`, any `Date` type values are mapped to `Timestamp` types while other types are left the same.

> Again, `ToFirestore<>` is a recursive conditional generic type because it calls itself on every object value type of `MaybeDate`.

```typescript
// If we have neither a `Date`, nor array nor object, just
// return back the same type because there's no transformation
// to be done
// highlight-range{7}
type ToFirestore<MaybeDate> = MaybeDate extends Date
  ? Timestamp
  : MaybeDate extends Array<infer Item>
  ? Array<ToFirestore<Item>>
  : MaybeDate extends Record<string, any>
  ? { [Key in keyof MaybeDate]: ToFirestore<MaybeDate[Key]> }
  : MaybeDate

type typeA = ToFirestore<string>
// ⮑ string
```

Finally, if we don't have a `Date` nor an array nor an object, we simply return the type back. **This is the termination condition of our recursive type.** This is how if we do `ToFirestore<string[]>` we get back `string[]`. It falls into the case where it does `Array<ToFirestore<string>>`. But since `ToFirestore<string>` becomes `string`, the result is `Array<string>` (or `string[]`).

---

The final solution was pretty fun to put together. And it took lots of refactoring to get it down to the single type expression (and not generate an endless recursive type). I like it because it has so many TypeScript type features all rolled in one. Not only is it a type expression, but it's a _generic_ type expression because it defines its own parameter, `MaybeDate`. It's also a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) and makes use of [mapped types](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html) & [`infer`](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#inferring-within-conditional-types). And to top it all off it's a recursive type. 🤯

If you've got any follow-up questions about how all of this generic type stuff works in TypeScript or got other feedback you would like to share, feel free to reach out to me on Twitter at [@benmvp](https://twitter.com/benmvp).

Keep learning my friends. 🤓


How to create complex conditional generic type expressions in TypeScript that can even be recursive

Creating custom generic TypeScript utility types

Unlock the Power of DivOps Engineering with Ben Ilegbodu and Jonathan Creamer

As web application architecture continues to evolve, the role of frontend engineers has expanded beyond `src/`. The need to enhance the developer experience and ensure project health has given rise to a new era of responsibilities for frontend developers. While these tasks may not involve building UI features directly, they encompass critical areas such as app configurations, build scripts, CI/CD maintenance, and more. But what should we call this disciple? Is it Frontend Platform? Frontend Infra? Frontend... DevOps?

This session introduces "DivOps," the fusion of Frontend and DevOps. Designed for web app developers of all levels, this talk deep dives into all the responsibilities of DivOps engineering and its major impact on our development environments, testing procedures, CI/CD workflows, and beyond. Through real-world examples and insights, you will gain a deeper understanding of the qualities that make a successful DivOps engineer and realize that you're likely one too.

Hi, I'm Ben Ilegbodu. I want to help you level up your frontend skills.

Read

Mock all functions in a JavaScript module except one using Jest

Create one-off releases with semantic-release

Putting test files in the pages folder in a Next.js app

Avoiding React act warning when accessibility testing next/link with jest-axe

Handling the React server hydration mismatch error

Creating custom generic TypeScript utility types

Watch

Unlock the Power of DivOps Engineering with Ben Ilegbodu and Jonathan Creamer

The Modern Web Podcast

"DivOps" Engineering: Unveiling the fusion of Frontend and DevOps

Connect.Tech 2023

Develop

Migrating to React Hooks

TypeScript for React Developers

Zero to React with Hooks