DEV Community: Prateek Surana

Why you should avoid using state for computed properties

Prateek Surana — Mon, 19 Jul 2021 14:38:05 +0000

I have often seen many people (including my past self) creating state variables for any kind of value that can change across renders including the ones that can be directly dervied from existing state or props. This pattern can often lead to some nasty and hard to debug state synchronization bugs, which can be easily avoided by computing those properties on the fly instead.

Let's try to understand with an example of what I meant in the above paragraph. Consider this example where we have a form with a field for name, and a submit button, which remains disabled until the user enters a name (A much better way to do this would be using HTML form validation, but don't forget this is a contrived example 😅). Right now, it has two state variables, one for keeping track of the name and the other for error (Try it out on codesandbox) -

function App() {
  const [name, setName] = React.useState("");
  const [hasError, setHasError] = React.useState(true);

  const handleNameChange = (event) => {
    const value = event.target.value;
    setName(value);
    setHasError(value.trim().length < 1);
  };

  return (
    <div className="App">
      <div className="form-item">
        <label>Name:</label>
        <input type="text" value={name} onChange={handleNameChange} />
      </div>
      <button disabled={hasError}>Submit</button>
    </div>
  );
}

Now, this might seem fine at first but imagine if a new requirement comes in, and you need to add a new field to the form, which is also required, so you would now need to update the hasError value there as well to keep the value in sync.

To exemplify the above problem, let's extend our above example by adding a field for age, and let's imagine the age needs to be greater than 18 years. (Try it out on codesandbox)

function App() {
  const [name, setName] = React.useState("");
  const [age, setAge] = React.useState(0);
  const [hasError, setHasError] = React.useState(true);

  const handleErrorUpdate = ({ currentName, currentAge }) => {
    setHasError(currentName.trim().length < 1 
      || currentAge < 18 
      || currentAge > 100);
  };

  const handleNameChange = (event) => {
    const value = event.target.value;
    setName(value);
    handleErrorUpdate({ currentName: value, currentAge: age });
  };

  const handleAgeChange = (event) => {
    const value =
      event.target.value.length > 0 
      ? parseInt(event.target.value, 10) 
      : 0;
    setAge(value);
    handleErrorUpdate({ currentName: name, currentAge: value });
  };

  return (
    <div className="App">
      <div className="form-item">
        <label>Name:</label>
        <input type="text" value={name} onChange={handleNameChange} />
      </div>
      <div className="form-item">
        <label>Age:</label>
        <input type="number" value={age} onChange={handleAgeChange} />
      </div>
      <button disabled={hasError}>Submit</button>
    </div>
  );
}

For the sake of DRY, I have moved the error update logic to a separate function. If we go by this logic, then we would have to call the handleErrorUpdate method every time we add or update a required form field. If we miss updating the error state, it can cause the hasError state to go out of sync and result in hard to debug errors for complex applications.

Now instead of doing it like this, we can calculate the error in a useEffect and set the error state there like this (Try it out on codesandbox) -

React.useEffect(() => {
  setHasError(name.trim().length < 1 || age < 18 || age > 100);
}, [name, age]);

And yes, this does simplify the code by removing the unnecessary code for calling the error handler wherever the relevant state is supposed to be updated. Also, if you're using eslint-plugin-react-hooks (which you should definitely use), it would warn you if you add some new variable to the setHasError logic and don't include it in the dependency array.

But what if there's something even better? As you can see, the hasError state is just being derived from the existing state that we already have in our component. So instead of maintaining a separate state for it, we can calculate it on the fly with every render like this -

const hasError = name.trim().length < 1 || age < 18 || age > 100;

This way, we wouldn't need to worry about hasError getting out of sync by introducing a new dependency. Also, it is a lot easier to understand and saves us an additional render. (Try it out on codesandbox)

One thing you might argue about is performance. Since we calculate this computed state property on every render wouldn't it be less performant than calculating it only when one of the dependent variables changes as we did previously?

The answer is yes, it depends. It could be if it's some computationally expensive calculation and variable that the calculation relies on don't change that often with every render, but guess what the React.useMemo hook is built exactly for these kinds of situations.

Although for most cases like the example we are working on, using React.useMemo would be a case of premature optimization because the variables depend on all the variables that cause a re-render, and it's not that expensive. You can also check out my article on when you should memoize if you are interested in exploring this topic further.

What about derived state from props?

For props as well, you can rely on the same pattern of directly deriving the desired values from props as we discussed in the previous section and avoid managing the state internally to steer clear of any state synchronization problems. So for our previous example, if the name and age values were provided via props from the parent component, our implementation for hasError would have remained the same.

function App ({ name, age }) {
  ...
  const hasError = name.trim().length < 1 || age < 18 || age > 100;
  ...
}

Although there are some edge cases where you need the props just for initial values and then manage them via some state internally.

Let's try to understand when you might run into a situation like this, with an example from this issue on the React repo asking the same question.

In this example, we have a list of items and every item has an edit button next to it, clicking on which opens an editor on the side where the user can edit the item properties and can save or cancel the updates. Currently, the item properties are passed as props to the editor component, which it then uses as initial values for its internal state, which handles the editor inputs.

This is what the code for the Editable list looks like -

import React, { useState } from "react";

const StatefulEditor = (props) => {
  const [name, setName] = useState(props.item.name);
  const [description, setDescription] = useState(props.item.description);

  return (
    <div className="editor">
      <input
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <input
        type="text"
        value={description}
        onChange={(e) => setDescription(e.target.value)}
      />
      <div className="button-container">
        <button
          onClick={() =>
            props.onConfirm({ id: props.item.id, name, description })
          }
        >
          Ok
        </button>
        <button onClick={props.onCancel}>Cancel</button>
      </div>
    </div>
  );
};

const EditableList = (props) => {
  const [itemUnderEdit, setItemUnderEdit] = useState(null);

  const closeEditor = () => setItemUnderEdit(null);
  const saveChangedItem = (itemToSave) => {
    props.handleItemUpdate(itemToSave);
    closeEditor();
  };

  return (
    <div className="editable-list">
      <div>
        {props.items.map((item) => (
          <div key={item.id}>
            {item.name}
            <button onClick={() => setItemUnderEdit(item)}>Edit</button>
          </div>
        ))}
      </div>
      {itemUnderEdit && (
        <StatefulEditor
          item={itemUnderEdit}
          onConfirm={saveChangedItem}
          onCancel={closeEditor}
        />
      )}
    </div>
  );
};

export default EditableList;

If you click on 'Ok' or 'Cancel' to close the editor after editing an item and then opening another item, this seems to be working fine. But try clicking on the edit button for any other item without closing the editor. You will notice the problem with this approach. The values in the editor remain the same even though the props have changed.

So why does this happen? It is because the state only gets initialized during the initial component mount, and even though the change in props cause a re-render, our useState cannot be re-initialized. This is one of the reasons why the React docs recommend avoiding this pattern.

But for our case, we have to rely on this pattern, so what can we do to keep the state and props in sync for this case?

Well, as it turns out, there are a few ways of fixing it. One is that you can add a key prop with the value as the id of your item to the Editor component. This would cause React to unmount the previous instance of the component and remount it causing our state to be initialized again whenever the props, i.e. the key with item id, change.

...
        <StatefulEditor
          key={item.id}
          item={itemUnderEdit}
          onConfirm={saveChangedItem}
          onCancel={closeEditor}
        />
...

This should suffice for most situations. If your component tree is expensive, then the above method can slightly affect performance because your component gets unmounted and remounted again. So what the React docs recommend is that you update the state during rendering, and React will re-run the component with updated state immediately after the current render. So in our case, this is what it would look like this -

const StatefulEditor = (props) => {
  const [name, setName] = useState(props.item.name);
  const [description, setDescription] = useState(props.item.description);
  const [id, setId] = useState(props.item.id);

  if (props.item.id !== id) {
    setName(props.item.name);
    setId(props.item.id);
    setDescription(props.item.description);
  }

  return (
    ...
  )
}

Here is the sandbox with the above fix, and if you check again you'll see that the issue is gone now -

Since this is a contrived example, it doesn't look great. In a real-world scenario, you might want to use useReducer if you have too many individual states to manage like this.

Conclusion

So I hope this article helped you understand why creating state variables for computed properties is not a good idea and how you can compute them on the fly instead and optimize via useMemo if needed. We also saw how you could sync state with props in some edge cases where you don't have any other reasonable option. You can also check out this article by Kent C. Dodd's, which talks about the same topic, with some additional thoughts on how you can handle it in other libraries as well.

Also, let me know in the comments section below if I have missed something or if you have better alternative ideas for the examples I used in this article.

Supercharge your git workflow with GitLens

Prateek Surana — Fri, 21 May 2021 18:47:33 +0000

This post will discuss some of my favorite features of the GitLens VSCode extension that might help you optimize your git workflow in VSCode.

Why bother using this extension?

Although VSCode has pretty good built-in git tools for basic git stuff like adding, committing, pushing, changing/creating branches. But if you want some additional features and want to "Supercharge your git workflow," then GitLens is possibly the best extension out there for this.

GitLens lets you do almost everything with git that you could imagine, directly from your code editor with a friendly GUI. I would go as far as to say that it even does stuff that I didn't even know was possible with git.

So here are some of my favorite GitLens features that I use regularly. You can find the full list of the features here.

1. Current line blame

This is probably the first feature you will notice when you install the extension. As soon as you hover over any line in the code (in a project using git and has some commits), you will be able to see this popover.

This popover gives you almost all the information that you might need for the current line like, what did the line looked like before the most recent commit that affected it, the commit hash that introduced the change, the PR that introduced the change (would need to connect to GitHub for this one), etc.

If you click on the open changes button, you will be able to view all the changes introduced by that commit in the current file.

Clicking on the commit hash in the popup gives you many options for that commit, like resetting, switching, or creating a branch from the commit, etc.

2. File blame

This is also a neat feature that allows you to view which lines were introduced by which commit and author for a particular file. This can be useful for exploring the history of the file and answering questions about which commit/PR introduced a particular set of changes and who made those commits.

To toggle file blame, you can either use the VSCode command palette (Cmd + Shift + P) and search for "GitLens: Toggle file blame" or use the keyboard shortcut (Option + Cmd + G B) to open it.

Once you are in the file blame mode, you can select the commits from the sidebar that appears next to the gutter to explore the changes introduced by that commit.

3. Commits view

After you install the extension it adds a new menu for some quick actions in your sidebar as well.

Although there are many sections in its sidebar menu, like repositories, file history, line history, etc., the one I use most often is the commits view.

It shows you all the commits of the current branch and again allows you to do a bunch of stuff like exploring the changed files in the commit, the PR that introduced the commit, etc.

If you right-click on a particular commit, you can take some actions over the commit like reset the commit, compare it with head, and, the one I use most often, switch to commit, which checks out the commit so you can explore the project in that commit state.

4. File heatmap

The usefulness of this feature might be arguable, but it is pretty cool, so I thought it deserved a spot on this list.

File heatmap shows you the spots in the file that have been changed most recently by adding a heatmap on the edge of the gutter. To enable it, search for "GitLens: Toggle File heatmap" via the VSCode command palette (Cmd + Shift + P).

Redder color means changes were made very recently in that area. Again you can fully customize age thresholds, locations, the color of the most recent and least recent changes, etc., from the settings.

5. Interactive rebase editor

Last but not least, GitLens also comes with a user-friendly interactive rebase editor, which lets you easily drop, squash re-order your commits during an interactive git rebase session.

This is an excellent tool for interactive rebases if you, like me, hate the vi editor that appears during interactive rebase with git.

To use this directly from your terminal (e.g., when you use git rebase -i ), run the following command to set VS Code as your git rebase editor -

git config --global core.editor "code --wait"

Conclusion

GitLens helps you better understand your code by "Supercharging," the git abilities build into VS Code. It allows you to explore the history and evolution of a codebase effortlessly.

With the features I explained here, I have barely scratched the surface of what this extension can do, and even I haven't explored most of the features yet, so feel free to share in the comments below if you find something interesting that deserves to be in the list.

When should you memoize in React

Prateek Surana — Sun, 18 Apr 2021 18:28:15 +0000

If you have heard about or used the React memoization methods (useMemo, useCallback, and memo), you might often get tempted to use them in situations where you might not need them.

When I first learned about these methods, I also often ended up using them everywhere because what harm optimizing something could do, right?

Well, as you might have guessed by now, I was wrong because these hooks and methods exist for some specific use cases, and if they're used mindlessly everywhere, they can actually worsen your app's performance.

In this article, I'll try my best to explain -

Why premature optimization is bad
How can you optimize your code without memoizing
When should you actually memoize

Why premature optimization is bad

useCallback

Let's start with an example. What do you think about, handleChange in the below code snippet?

const MyForm = () => {
  const [firstName, setFirstName] = React.useState('');

  const handleSubmit = event => {
    /**
     * Omitted for brevity
     */
  };

  const handleChange = React.useCallback(event => {
    setFirstName(event.target.value);
  }, []);

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" name="firstName" onChange={handleChange} />
      <button type="submit" />
    </form>
  );
};

I used to think that useCallback improves performance by returning a memoized callback that only changes if one of the dependencies changes. In our case, since the dependency array is empty, it would get memoized and would be more efficient than the normal inline function, right?

But, it's not as simple as that, because every optimization comes with a cost associated with it. And in the above case, the optimization is not worth the cost it comes with. But why?

const handleChange = React.useCallback(event => {
    setFirstName(event.target.value);
}, []);

In the above case, useCallback() is called every time our MyForm component re-renders. Even though it returns the same function object, still the inline function is created on every render, useCallback just skips it to have the same reference to the function. Not only that, but we also have the empty dependency array, which itself is doing some work by running through some logical expressions to check if the variables inside have changed, etc.

So this is not really an optimization since the optimization costs more than not having the optimization. Also, our code is a bit more difficult to read than it was before because of the function being wrapped in a useCallback.

And as far as inline functions go, this is what the official documentation on the React website says, and they are not actually as bad as you think they are.

useMemo different yet similar

useMemo is also very similar to useCallback, with the only difference that it allows memoization to any value type. It does so by accepting a function that returns a value and is only recomputed when the items in the dependency list change. So again, if I didn't want to initialize something on every render, I could do this right?

const MightiestHeroes = () => {
  const heroes = React.useMemo( () => 
    ['Iron man', 'Thor', 'Hulk'], 
  []);

    return (
        <>
            {/* Does something with heroes, Omitted for brevity */}
        </>
    )

}

Again the savings are so minimal that making the code more complex isn't worth it, and it's probably worse because of the same reasons, which we discussed in the previous section.

For a case like this, you would be much better off by defining the array outside the component.

const heroes = ['Iron man', 'Thor', 'Hulk'];

const MightiestHeroes = () => {
    // Ommited for brevity 

}

Edge cases with memo

The same thing goes with memo, if we're not careful enough your memoized component might end up doing more work and hence being more inefficient than the normal counterpart

Take this sandbox for example, how many times do you think this memoized component will render when you are incrementing the count.

But shouldn't it render only once because it takes only one children prop which doesn't appear to be changing across renders?

memo does a shallow comparison of the previous props and the new props and re-renders only when the props have changed. So if you've been working with JavaScript for some time then you must be aware of Referential Equality -

2 === 2 // true
true === true // true
'prateek' === 'prateek' // true

{} === {} // false
[] === [] // false
() => {} === () => {} // false

And since typeof children === 'object, the equality check in memo always returns false, so whenever the parent re-renders, it will cause our memoized component to re-render as well.

How can you optimize your code without memoizing

In most cases, check if you can split the parts that change from the parts that don't change, this will probably solve most of the problems without needing to use memoization. For example, in the previous React.memo example, if we separate the heavy lifting component from the counting logic, then we can prevent the unnecessary re-renders.

You can checkout Dan Abramov's article Before you Memo if you want to read more about it.

But in some cases, you would need to use the memoization hooks and functions, so let's look at when you should use these methods.

When should you actually memoize

useCallback and useMemo

The main purpose of useCallback is to maintain referential equality of a function when passing it to a memoized component or using it in a dependency array (since functions are not referentially equal, as discussed above). For useMemo apart from referential equality and like memo, it is also a way to avoid recomputing expensive calculations. Let's understand how they work with some examples -

Referential Equality

First, let's see how these hooks help us maintain referential equality, take a look at the following example (keep in mind that this is a contrived example to explain the use case of these hooks, actual implementations will vary)

const PokemonSearch = ({ weight, power, realtimeStats }) => {
  const [searchquery, setSearchQuery] = React.useState('');

  const filters = {
    weight,
    power,
    searchquery,
  };

  const { isLoading, result } = usePokemonSearch(filters);

  const updateQuery = newQuery => {
    /**
     * Some other stuff related to
     * analytics, omitted for brevity
     */
    setSearchQuery(newQuery);
  };

  return (
    <>
      <RealTimeStats stats={realtimeStats} />

      <MemoizedSearch query={searchquery} updateQuery={updateQuery} />

      <SearchResult data={result} isLoading={isLoading} />
    </>
  );
};

const usePokemonSearch = filters => {
  const [isLoading, setLoading] = React.useState(false);

  const [result, setResult] = React.useState(null);

  React.useEffect(() => {
    /**
     * Fetch the pokemons using filters
     * and update the loading and result state
     * accordingly, omitted for brevity
     */
  }, [filters]);

  return { result, isLoading };
};

In this example, we have a PokemonSearch component that uses the usePokemonSearch custom hook to fetch the pokemons for a given set of filters. Our component receives the weight and power filters from the parent component. It also receives a prop for real-time stats, which changes quite often, as the name suggests.

Our component itself handles the last filter, called searchQuery, via useState. We pass this filter to a memoized component called MemoizedSearch with a method to update it called updateQuery.

You might have noticed by now the first problem with our example, every time our PokemonSearch re-renders, a new reference of our updateQuery function would be created (which would not be equal to the previous reference because of how referential equality works in JavaScript), causing the MemoizedSearch component to re-render unnecessarily, even when the searchQuery is same.

This is where useCallback saves the day -

const updateQuery = React.useCallback(newQuery => {
    /**
     * Some other stuff related to
     * analytics, omitted for brevity
     */
    setSearchQuery(newQuery);
}, []);

This would help us in maintaining the same reference of the updateQuery function which will avoid the unnecessary re-renders of our MemoizedSearch component causing it to re-render only when the searchQuery changes.

If you check the usePokemonSearch custom hook, it has a useEffect that relies on the filters prop to decide whether to fetch the details of the pokemons whenever it changes. I hope that you noticed the next problem with our example as well. Every time the PokemonSearch re-renders, let's suppose not due to the change in one of the filters, it creates a new reference to our filters object, which won't be referentially equal to the last one causing the useEffect to run with every render of PokemonSearch and hence making a lot of unnecessary API calls.

Let's fix this with useMemo -

const filters = React.useMemo(() => ({
  weight,
  power,
  searchquery,
}), [weight, power, searchQuery]);

Now the filter object reference will only be updated when either of our filter changes, thus calling the useEffect only when one of our filters change.

So the final code with all the optimizations looks like this -

const PokemonSearch = ({ weight, power, realtimeStats }) => {
  const [searchquery, setSearchQuery] = React.useState('');

  const filters = React.useMemo(() => ({
    weight,
    power,
    searchquery,
  }), [weight, power, searchQuery]);

  const { isLoading, result } = usePokemonSearch(filters);

  const updateQuery = React.useCallback(newQuery => {
    /**
     * Some other stuff related to
     * analytics, omitted for brevity
     */
    setSearchQuery(newQuery);
  }, []);

  return (
    <>
      <RealTimeStats stats={realtimeStats} />

      <MemoizedSearch query={searchquery} updateQuery={updateQuery} />

      <SearchResult data={result} isLoading={isLoading} />
    </>
  );
};

const usePokemonSearch = filters => {
  const [isLoading, setLoading] = React.useState(false);

  const [result, setResult] = React.useState(null);

  React.useEffect(() => {
    /**
     * Fetch the pokemons using filters
     * and update the loading and result state
     * accordingly, omitted for brevity
     */
  }, [filters]);

  return { result, isLoading };
};

Avoiding recomputing expensive calculation

Apart from referential equality, the useMemo hook, similar to the memo function, serves one more purpose of avoiding recomputing expensive calculations with every render if they are not required.

For instance, take the following example, if you try to update the name really fast, you will be able to see a certain lag because the 35th Fibonacci number (which is purposefully slow and blocks the main thread while computing) is getting calculated every time your component re-renders even though the position remains the same.

Now let's try this with useMemo. Try updating the name really fast again and see the difference -

With useMemo we only re-calculate the Fibonacci number only when the position changes thus avoiding the unnecessary main thread work.

memo

If your component re-renders the same result given the same props, React.memo can give you a performance boost by skipping re-rendering if the props haven't changed.

Dmitri created a really nice illustration in his article Use React.memo() Wisely which you should use a general rule of thumb when you're thinking about memoizing a component.

Enough with the concepts, let's try to understand this with an example on when React.memo can be handy. In the below sandbox, we have a usePokemon hook that returns some static and real-time data for a pokemon.

The static details include the name image and abilities of the Pokemon. In contrast, the real-time info includes details like the number of people who want this Pokemon and the number of people who own the Pokemon, which change quite often.

These details are rendered by three components PokemonDetails which renders the static details, and Cravers and Owners, which render the real-time info, respectively.

Now, if you check the console in the above sandbox, it doesn't look good because even though PokemonDetails consist of static data, it still re-renders every time any of our real-time values change, which is not very performant. So let's use the Checklist by Dmitri mentioned above to see if we should memoize it -

Is it a pure functional component, that given the same props renders the same output?

Yes, our PokemonDetails component is functional and renders the same output with the same props ✅
Does it re-render often?

Yes, it re-renders often because of the realtime values provided by our custom hook ✅
Does it re-render with the same props?

Yes, the props it uses don't change at all across all its renders ✅
Is it a medium to big size component?

Since this is a very contrived example, it isn't really isn't in the sandbox, but for the sake of this example let's assume it is (Although even though isn't very expensive but given that it satisfies the above three conditions it still is a pretty good case for memoization) ✅

Since our component satisfies the above conditions, let's memoize it -

If you check the console in the above sandbox, you'll see that it gets re-rendered only once, optimizing our code quite a bit by saving us potentially expensive re-renders.

Conclusion

If you've reached this far, I assume you get the point I am trying to make here. I'll repeat it every optimization you do comes with a cost associated with it, and the optimization is only worth it if the benefits outweigh the cost. In most cases, you might even not need to apply these methods if you can separate the parts that often change from the parts that don't change that much, as we discussed above.

I know it's a bit annoying, and maybe in the future, some really smart compiler could automatically take care of these things for you, but till then, we would have to be mindful while using these optimizations.

Have I read this before?

You might have because some parts of it were inspired by this excellent post by Kent C. Dodds. I liked the article, and I wanted to share some more ideas with some examples of situations that I have faced. And I have still seen many blog posts and code snippets that use these methods where they are not needed, so I thought this deserved more attention.

JavaScript tips for React Developers

Prateek Surana — Sun, 28 Feb 2021 18:35:04 +0000

I have been working with React for the past couple of years, so naturally, I am not really proud of the code that I wrote when I was just beginning with React, because now I know the mistakes I made which I wasn't aware of back then.

But fast-forwarding to today, I have learned quite a bit along the way through contributing to open-source, watching/reading some interesting blogs and conference talks and viewing how other people write code.

Here are some Javascript tips that would've helped my past self and maybe you, in writing more efficient and maintainable React code -

1. Use conditional rendering effectively

As a React developer, you must've been in a situation where you only want to display a component when a certain condition from a prop or state is satisfied or render different components depending on the different values of the state.

For instance, if you have a component where you want to show a loading indicator when the request is being made and render the component with data when the request is successful, this is the way I like to do it -

const SomeComponent = ({ isLoading, data }) => {

    if(isLoading) {
    return <Loader/>
  }

  return (
     <DataHandler>
       .
       .
     </DataHandler>
  );

}

But what if you want to render something inside JSX when a particular condition is satisfied in that case you can use the Logical AND operator (&&) to render it -

const Button = ({ showHomeIcon, children, onClick }) => (
  <button type="button" onClick={onClick}>
    {showHomeIcon && <HomeIcon />}
    {children}
  </button>
);

Although a more useful scenario would be doing something like this, where you have an optional prop called icon which is a string and contains the name of the icon that can be used to render the icon component accordingly -

const Button = ({ icon, children, onClick }) => (
  <button type="button" onClick={onClick}>
    {/* Icon won't be rendered if the value of
        icon prop is anything other than a string */}
    {typeof icon === "string" && <Icon name={icon} />}
    {children}
  </button>
);

// Renders a button with a home icon
<Button icon="home" onClick={handleClick}>Home</Button>

// Renders a button without an icon
<Button onClick={handleClick}>About</Button>

So this solves the problem when you only have one component but what about when you have two or more than two components that you want to render based on some prop or state variable?

For two components ternary operator is my goto method, because of its simiplicity -

const App = props => {
  const canViewWelcomeText = isUserAuthenticated(props);

  return canViewWelcomeText ? (
    <div>Hey, there! Welcome back. Its been a while.</div>
  ) : (
    <div>You need to login to view this page</div>
  );
};

And if you have quite a few components that need to be rendered from a condition, then switch case is probably the best one to go with -

const getCurrentComponent = currentTab => {
  switch (currentTab) {
    case 'profile':
      return <Profile />;
    case 'settings':
      return <Settings />;
    default:
      return <Home />;
  }
};

const Dashboard = props => {
  const [currentTab, setTab] = React.useState('profile');

  return (
    <div className="dashboard">
      <PrimaryTab currentTab={currentTab} setTab={setTab} />
      {getCurrentComponent(currentTab)}
    </div>
  );
};

2. Avoid using truthy tests

If you are familiar with JavaScript then you might be aware of truthy and falsy values. So a truthy test is nothing but using this coercion ability of JavaScript in control flow statements like this

// ❌ Avoid adding checks like these 
// for non boolean variables
if (somVar) {
    doSomething();
}

This might look good at first if you want to avoid something like null since it is a falsy value so the statement will work as expected. But the catch here is that this is prone to bugs that can be very difficult to track down. This is because the above statement would block the flow for not null but also for all these falsy values of someVar which we might want to avoid -

someVar = 0
someVar = ""
someVar = false
someVar = undefined

So what is the correct way for these checks?

The valid way is being as straightforward as possible for these checks to avoid any bugs from creeping in. For the above case it would be -

// ✅ Explictly check for the conditions you want
if (someVar !== null) {
    doSomething();
}

If you're sure that the variable being passed is a boolean then you can use the former approach.

This also applies when doing conditional rendering with the Logical and operator that we saw in the previous tip.

If the first operator is falsy then JavaScript returns that object. So in case of an expression like 0 && "javascript" will return 0 and false && "javascript" will return false . This can bite you if you were doing something like this -

// ❌ This will end up rendering 0 as the text if 
// the array is empty
{cats.length && <AllCats cats={cats} />}

// ✅ Use this instead because the result of the 
// condition would be a boolean
{cats.length > 0 && <AllCats cats={cats} />}

3. Use optional chaining and nullish coalescing

When dealing with data in our apps we often need to deal with parts of data that call be null or undefined and provide default values.

Let's suppose we have an API that returns the details of a Pet in the following format -

// Endpoint - /api/pets/{id}
{
  id: 42,
  name: 'Ghost',
  type: 'Mammal',
  diet: 'Carnivore'
  owner: {
    first_name: 'Jon',
    last_name: 'Snow',
    family: {
      name: 'Stark',
      location: 'Winterfell'
    }
  }
}

So you could do something like this if you wanted the first name of the pet owner

const ownerName = pet.owner.first_name;

But like all things in the universe can't be perfect, our API doesn't guarantee that all the details would be available for any given pet and can be null or undefined.

In that case, the above line of code can result and the following error "Reference error cannot read property first_name of null" and crash your app if the owner is null.

This is where optional chaining saves you. The optional chaining operator (?.) allows you to read the property deep in the chain without having to validate whether the chain is valid, and instead of a reference error, it would return the same old undefined.

So we could easily check for the owner name or even the owner family name without worrying about any errors, like this -

const ownerName = pet?.owner?.first_name;
const ownerFamily = pet?.owner?.family?.name;

Optional chaining can also be used with function calls on properties you are not really sure to exist. For instance, you can do this with an array friends?.join(",") , this won't result in an error if friends is anything other than an array, even undefined.

Now, this would avoid errors but you still wouldn't want your users to show undefined in case it is not available. This is where Nullish Coalescing comes in -

const ownerName = pet?.owner?.first_name ?? 'Unknown';

The Nullish Coalescing operator (??) returns the right hand side operand when the left hand side is null or undefined and otherwise it returns the left hand side operand.

You might think here that the Logical Or operator (||) would also have done the same thing. Well in that case I hope you haven't forgotten the truthy and falsy hell of JavaScript that we just covered. Since this operator would return the right hand side operand for all falsy values and can cause hard to debug errors as mentioned in the previous section.

Since these methods were recently released with ECMAScript 2020 spec browser compatibility for these methods is still in the preliminary stages and only the modern browsers support it right now.

But don't worry most setups we use to compile our apps have already got us covered. If you're using TypeScript ≥ 3.7 then these methods are supported out of the box.

Else if you're using a typical Webpack + babel setup then you can include the @babel/plugin-proposal-optional-chaining and @babel/plugin-proposal-nullish-coalescing-operator plugins in your babel config to support these methods.

4. Avoid premature optimization

Be really careful when you want to memoize something in React, because if not done properly it might lead to even worse performance.

I have often seen people prematurely optimizing everything they come across without considering the cost it comes with. For instance, using useCallback in situations like this -

const MyForm = () => {
  const [firstName, setFirstName] = React.useState('');

  const handleSubmit = event => {
    /**
     * Ommitted for brevity
     */
  };

  // ❌ useCallback is unnecessary and can actually be worse for performance
  const handleChange = React.useCallback(event => {
    setFirstName(event.target.value);
  }, []);

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" name="firstName" onChange={handleChange} />
      <button type="submit" />
    </form>
  );
};

Now you might've heard that useCallback is known to improve performance by memoizing the function and only updating it when the dependencies change. That is true but you need to understand that every optimization comes with a cost associated with it.

In the above case, you are doing more work by creating a useCallback which in itself is running some logical expression checks, hence you're better off with just defining the inline function directly like this -

const handleChange = event => {
    setFirstName(event.target.value);
};

The same things apply with React.memo. If you have a component like this that accepts children props, then memoizing the component is basically useless if the children are not memoized -

const UselessMemoizedHeader = React.memo(({ children }) => <div>{children}</div>);

const SomeComponent = () => {
  const [count, setCount] = React.useState(0);
  return (
    <div>
      <UselessMemoizedHeader>
        <span>Header</span>
      </UselessMemoizedHeader>
      Count: {count}
      <button type="button" onClick={() => setCount(currentCount => currentCount + 1)}>
        Increment count
      </button>
    </div>
  );
};

In the above case, the UselessMemoizedHeader component would re-render every time you increment the count even though you might think it is memoized.

But why? Since memo just does a shallow comparison of the current props and previous props, and because the children prop won't be refrentially equal you end up re-rendering the UselessMemoizedHeader component every time the count changes.

Your code ends up being even worse off because of that unnecessary children prop comparison on every render.

So when do you actually need to memoize? Well Kent C. Dodds covers all the above things with when you should memoize in great detail in his article. I would recommend you give it a read.

5. Be vigilant with dependency arrays

The React hooks related to memoization(useCallback and useMemo) and the useEffect hook take a second argument as an array usually known as dependency array.

In case of useEffect the effect is re-run only when a shallow equality check of the dependency array is not equal to the previous values.

React.useEffect(() => {
  /**
   * Fetch data with new query
   * and update the state
   */
}, [query]); // < The effect reruns only when the query changes

Similarly, the memoization hooks, are recomputed only when the values in their dependency array change

const someValue = React.useMemo(() => 
  computationallyExpensiveCalculation(count), 
[count]); // < someValue is recomputed only when count changes

So now that's clear. Can you find out why does the effect runs everytime the CatSearch component re-renders, even when the query, height and color props are essentially the same -

const CatSearch = ({ height, color, query, currentCat }) => {
  const filters = {
    height,
    color,
  };

  React.useEffect(() => {
    fetchCats(query, filters);
  }, [query, filters]); // ❌ This effect will run on every render

  return (
    /**
     * Ommited for brevity
     */
  );
};

Well as we discussed in the last section, React just does a shallow comparison of the items in the dependency array and since the filter object gets created in every render it can never be referentially equal to the filter object in the previous render.

So the correct way to do this would be -

React.useEffect(() => {
    fetchCats(query, { height, color });
}, [query, height, color]); // ✅ The effect will now run only when one of these props changes

The same applies for spreading the dependencies like this -

React.useEffect(() => {
   /**
    * Ommited for brevity
    */
}, [...filterArray, query]); // ❌ This effect would also run on every render

If you are using ESLint as your linter then you should definitely install the eslint-plugin-react-hooks, it will warn you and even fix issues automatically (if autofix on save is enabled) for most of the mistakes people generally make with these hooks.

Also if you're more interested in how useEffect works and how the dependency array affects the effect, then you should definitely check out A Complete Guide to useEffect by Dan Abramov.

If you made it this far, then I hope you learned something new from this article. If you did then do share it on Twitter.

Integrating reCAPTCHA with Next.js

Prateek Surana — Mon, 18 Jan 2021 13:49:55 +0000

In this post on integrating reCAPTCHA with Next.js, we will be looking at what is a CAPTCHA, how does it work and why you might need it. Then we'll work on a demo to illustrate how you can take advantage of Next.js features to integrate it nicely with your website.

So you must've probably seen this before, but have you ever wondered what it does?

A CAPTCHA is a Turing test designed to tell humans and bots apart and is generally used by websites to prevent spam and abuse. It uses a challenge that is easy for humans but hard for bots.

reCAPTCHA is a CAPTCHA system currently being maintained by Google. The currently maintained versions are v2, which uses an analysis of cookies, canvas rendering, and user behavior to decide whether to show a challenge or not, and v3, which does not interrupt the users at all.

To get the full benefits of reCAPTCHA, you need to verify the captcha response code in the server to verify its validity. With Next.js, this could have never been easier since it easily lets you spin up a serverless function (if you're deploying it via Vercel) just by adding an API route in the /pages/api/ folder.

This post assumes you are familiar with the basics of React and Next.js. If not, I would recommend checking out the Intro to React Tutorial by the React team and the Next.js tutorial from the docs.

reCAPTCHA, though more famous than any other solutions out there but is infamous for its privacy-related concerns. So if you are concerned about your user's privacy, we will also be looking at a privacy-friendly alternative to reCAPTCHA called hCaptcha later in this post.

We will cover this with the following steps -

Why you might need to use reCAPTCHA and how does it work
Setting up the project
Adding reCAPTCHA to the frontend
Verifying captcha via Next.js' API routes
Bonus: Integrating hCaptcha and why you might need it

Why you need to use reCAPTCHA and how does it work

Before we dive into integrating reCAPTCHA, let's take a moment to understand why you need it and how does it solve your problems.

If you have a public-facing page with a form that sends the data to your backend server, then adding reCAPTCHA can help you to prevent spammers/bots from flooding your form and thus polluting your database or prevent something like brute force password guessing attack on a login page. Although reCAPTCHA is not the only way to prevent such malicious requests, there are other ways you can prevent spam without disturbing your users. Still, reCAPTCHA is really smart and only shows a challenge if your user fails its cookie and behavior analysis.

The way it works is as soon as the user submits the form, you execute the reCAPTCHA instead of sending the data directly to your backend. In turn, reCAPTCHA provides you a callback for both success and failure, which will be executed if the user passes or fails the reCAPTCHA, respectively.

Now this will prevent your frontend from malicious attacks. However, your backend APIs might still be insecure (assuming you are not using any other kind of protection, e.g., CSRF tokens) because anyone can open the network tab to check the APIs getting pinged and run a script to ping the API with spam data. Thankfully reCAPTCHA provides a solution for that as well. When a user successfully clears the reCAPTCHA, you are provided with a token that is valid for 2 minutes. You can now validate this token in your backend with a secret key to verify the request's authenticity.

Setting up the project

I will be using a plain starter built using create-next-app with a simple form. If you want to follow along, you can get the initial state from this commit. The initial setup looks like this, and it just shows your email in an alert when you click on register

Let's register a new project on reCAPTCHA and get the required keys. For that, you can go to the reCAPTCHA admin console, fill in the required details as mentioned below, and click on submit.

For this post's scope, we will be focusing on the v2 Invisible reCAPTCHA which does not involves the reCAPTCHA checkbox. It invokes the prompt to solve captcha for most suspicious traffic via a JavaScript API call and will directly tell us if the user has passed or not.

v3 reCAPTCHA, though, is more advanced and doesn't require users to solve any challenge, but only provides a score between 0 and 1, requiring you to take action in the context of your site: for instance, requiring additional factors of authentication, sending a post to moderation, or throttling bots that may be scraping content.

Notice how I added the only localhost to the list of domains. That's because we would only be using these keys for development purposes. reCAPTCHA also does a domain validation for the site it is being executed on, so we would be creating a separate set of keys for the production environment to only be used on the production domain and not be misused.

After clicking submit, you should be able to see the public and secret keys.

To have separate keys for production and development environments and avoid pushing these keys to version control, we would store these keys in the environment variables. Unlike typical react app setups where you would need to manually setup environment variables manually via Webpack plugins, Next.js comes with built-in support for environment variables. For the development environment, create a file called .env.local and add the following to it, and paste the keys you copied from the reCAPTCHA dashboard here appropriately.

# Add the public site key here
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=
# Add the secret key here
RECAPTCHA_SECRET_KEY=

You can use different environment keys for production with the proper domains added, either using .env.production.local or adding the production environment variables to the tool (e.g., Vercel) you are using to deploy your app.

👨🏻‍💻 Code till this step

Adding reCAPTCHA to the frontend

We need the public site key to be available to the client. Adding the NEXT_PUBLIC_ suffix to the environment variable would make it visible to the browser. The RECAPTCHA_SECRET_KEY environment variable would only be available on the server.

We would be using a library called react-google-recaptcha, a wrapper around reCAPTCHA v2 that provides access to its APIs via a React component. Let's install it -

yarn add react-google-recaptcha

Since we are using the v2 invisible reCAPTCHA, we would be executing it when we submit the form via a React ref. Import the ReCAPTCHA component and place it in the pages/index.js file, like this -

import React from "react";
import Head from "next/head";
import ReCAPTCHA from "react-google-recaptcha";

export default function Home() {
  const [email, setEmail] = React.useState("");
  const recaptchaRef = React.createRef();
  .
  .
  .
  .
    <form onSubmit={handleSubmit}>
      <ReCAPTCHA
        ref={recaptchaRef}
        size="invisible"
        sitekey={process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY}
      onChange={onReCAPTCHAChange}
      />
      <input
        onChange={handleChange}
        required
        type="email"
        name="email"
        placeholder="Email"
      />
      <button type="submit">Register</button>
    </form>
 .
 .
 );
}

For the siteKey we are using the environment variable that we created in the last step.

We now need to execute the reCAPTCHA when submitting the form and do what we want when our form is submitted in the ReCAPTCHA component's onChange handler when the captcha is completed. So let's modify the handleSubmit function and define the onReCAPTCHAChange function accordingly in our component -

const handleSubmit = (event) => {
  event.preventDefault();
  // Execute the reCAPTCHA when the form is submitted
  recaptchaRef.current.execute();
};

const onReCAPTCHAChange = (captchaCode) => {
  // If the reCAPTCHA code is null or undefined indicating that
  // the reCAPTCHA was expired then return early
  if(!captchaCode) {
    return;
  }
  // Else reCAPTCHA was executed successfully so proceed with the 
  // alert
  alert(`Hey, ${email}`);
  // Reset the reCAPTCHA so that it can be executed again if user 
  // submits another email.
  recaptchaRef.current.reset();
}

When you restart the server with yarn dev, if the integration was successful you should see the reCAPTCHA badge at the bottom right corner. And you would be only able to see the alert if you pass the reCAPTCHA.

Note that if a challenge is not being shown to you, it doesn't necessarily mean that there is something wrong with the integration. As I mentioned earlier, reCAPTCHA only shows a challenge if you fail its behavior or cookie analysis. If you still want to see the challenge anyways, you can open the tab in incognito and update the security preference to most secure from the reCAPTCHA admin dashboard.

You should be able to see the challenge after submitting a form couple of times in a row.

👨🏻‍💻 Code till this step

Verifying captcha via Next.js' API routes

Likely, you don't want to show your user's info in an alert box when he submits your form. You might want to store that info somewhere in your backend instead or provide an appropriate response to the user in case of a login form. For that, we can replace the code that shows the alert with an API call that saves the info the user entered to your backend because we have already added the reCAPTCHA that would prevent any bot or spammers, right?

Well, not really. As I mentioned in the beginning if you're not using any protection for your API and since the API is most probably open, someone can still run a simple script that continuously pings your API with garbage data polluting your database.

Don't worry Next.js and reCAPTCHA have you covered.

Remember the reCAPTCHA token you received in the onReCAPTCHAChange function. That token can be used to verify whether the request you just received is legitimate or not. Google provides an API for verifying that token in your server via the secret key. The token is valid only for 2 minutes and can only be verified once to prevent any replay attacks.

So do you need to update your API route that saves the user details or create a new server that would handle the verification if you're relying on some third party API?

This is where Next.js' API routes come in. If you're using Vercel for deployment, it spins up a serverless function whenever you create a new API route.

For our demo, we need an API endpoint that accepts the email and the captcha token and saves the email to the database if the token is valid, and returns an error if it is bogus.

Let's create our API route, create a file called pages/api/register.js and paste the following in it -

// pages/api/register.js
import fetch from "node-fetch";

const sleep = () => new Promise((resolve) => {
  setTimeout(() => {
    resolve();
  }, 350);
});

export default async function handler(req, res) {
  const { body, method } = req;

  // Extract the email and captcha code from the request body
  const { email, captcha } = body;

  if (method === "POST") {
    // If email or captcha are missing return an error
    if (!email || !captcha) {
      return res.status(422).json({
        message: "Unproccesable request, please provide the required fields",
      });
    }

    try {
      // Ping the google recaptcha verify API to verify the captcha code you received
      const response = await fetch(
        `https://www.google.com/recaptcha/api/siteverify?secret=${process.env.RECAPTCHA_SECRET_KEY}&response=${captcha}`,
        {
          headers: {
            "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
          },
          method: "POST",
        }
      );
      const captchaValidation = await response.json();
      /**
       * The structure of response from the veirfy API is
       * {
       *  "success": true|false,
       *  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
       *  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
       *  "error-codes": [...]        // optional
        }
       */
      if (captchaValidation.success) {
        // Replace this with the API that will save the data received
        // to your backend
        await sleep();
        // Return 200 if everything is successful
        return res.status(200).send("OK");
      }

      return res.status(422).json({
        message: "Unproccesable request, Invalid captcha code",
      });
    } catch (error) {
      console.log(error);
      return res.status(422).json({ message: "Something went wrong" });
    }
  }
  // Return 404 if someone pings the API with a method other than
  // POST
  return res.status(404).send("Not found");
}

For simplicity, I have installed a package called node-fetch, which is a light-weight wrapper that provides the window.fetch like API in Node environment.

Now let's integrate this API on the client. Update the onReCAPTCHAChange function in the pages/index.js with the following snippet -

const onReCAPTCHAChange = async (captchaCode) => {
    // If the reCAPTCHA code is null or undefined indicating that
    // the reCAPTCHA was expired then return early
    if (!captchaCode) {
      return;
    }
    try {
      const response = await fetch("/api/register", {
        method: "POST",
        body: JSON.stringify({ email, captcha: captchaCode }),
        headers: {
          "Content-Type": "application/json",
        },
      });
      if (response.ok) {
        // If the response is ok than show the success alert
        alert("Email registered successfully");
      } else {
        // Else throw an error with the message returned
        // from the API
        const error = await response.json();
        throw new Error(error.message)
      }
    } catch (error) {
      alert(error?.message || "Something went wrong");
    } finally {
      // Reset the reCAPTCHA when the request has failed or succeeeded
      // so that it can be executed again if user submits another email.
      recaptchaRef.current.reset();
      setEmail("");
    }
  };

To test if the integration is proper, you can replace the captcha code sent to the API with a random string, and you should see this when you click on register.

If you followed along till here, then pat yourself on the back. Your frontend and backend database are now fully secure from any spam or bots.

👨🏻‍💻 Code till this step

Bonus: Integrating hCAPTCHA and why you might need it

Although reCAPTCHA might be great for security, but if you're concerned about your user's privacy, then hCaptcha might be a better choice. Do checkout why Cloudflare moved from reCAPTCHA to hCaptcha. hCaptcha differs from reCAPTCHA in the following ways:

They respect for your user's privacy.
Your visitors will solve problems that benefits many companies for labelling the data instead of a single corporation.
It's more user friendly and contains a variety of challenges.

Thanks to hCaptcha's clean and similar to reCAPTCHA APIs, it takes no time to switch from reCAPTCHA to hCaptcha. It literally took me just 15 minutes to go through their docs and replace reCAPTCHA with hCaptcha for our demo.

The setting up process is very similar to reCAPTCHA. You can go to their signup page to create an account and get the site key and secret key for your site. I renamed the keys to NEXT_PUBLIC_HCAPTCHA_SITE_KEY and HCAPTCHA_SECRET_KEY, respectively, in the .env.local file.

They also have a React wrapper component called @hcaptcha/react-hcaptcha, which also has a very similar API to the React component we used for reCAPTCHA. These are the only changes (apart from renaming reCAPTCHA variables) I had to integrate the component on the client in pages/index.js :

.
.
import HCaptcha from "@hcaptcha/react-hcaptcha";
.
.
.
<HCaptcha
  id="test"
  size="invisible"
  ref={hcaptchaRef}
  sitekey={process.env.NEXT_PUBLIC_HCAPTCHA_SITE_KEY}
  onVerify={onHCaptchaChange}
/>

For the api route, we just need to change the url and pass the secret and token to the body instead of query params, this is what it looks like in pages/api/register.js :

const response = await fetch(
  `https://hcaptcha.com/siteverify`,
  {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
    },
    body: `response=${captcha}&secret=${process.env.HCAPTCHA_SECRET_KEY}`,
    method: "POST",
  }
);

Although hCaptcha doesn't work on localhost URLs so you would need to add a host entry for localhost according to your system for it to work.

After that you can just run yarn dev, and visit the URL you added the host entry for localhost to to see hCaptcha in action

I created a separate branch in the demo repo, for the hCaptcha integration here -

👨🏻‍💻 Code till this step

I hope this article helped you in gaining some insight on how you can integrate CAPTCHA with your Next.js website and which CAPTCHA service you should prefer. If it did then do share it on twitter and follow me for more.

You can find the full code for both the reCAPTCHA and hCaptcha integration on GitHub.

Creating a React component library using Storybook 6

Prateek Surana — Sun, 20 Dec 2020 15:58:52 +0000

If you have multiple projects that are using the same design system (inputs, buttons, other reusable components, etc.), then you probably have a good enough use case to create a shared component library that can be published and consumed directly by all your projects.

Another benefit is that you can develop UI components easily in isolation and render their different states directly, without needing to mess with the business logic in your dev stack, with the help of Storybook.

In this tutorial, I would be covering the steps for creating and publishing a React component library (Storybook supports countless other frontend frameworks), with the following steps -

Setting up the project
Installing Storybook
Adding stories and setting up the file structure
Compiling the Library using Rollup
Publishing and consuming the library

Setting up the project

Since we are building a component library that would be published to a package manager like NPM, we would be better off if we setup React from scratch instead of using something like create-react-app, which is better suited for web applications.

If you have a component library using React already setup, then you can directly move forward to the next step. We just need a basic React setup before we can install Storybook.

For that, create a new folder with whatever name you want for your component library. I would be calling mine my-awesome-component-library.

Then run yarn init and git init, respectively, in that folder providing appropriate values for the fields asked. This would initialize an empty NPM project with git. Also, set up a gitignore file.

We are building a React component library, so we would need to React to build our components. Also, we are going to use TypeScript to build our library. Let's add that too.

yarn add --dev react react-dom @types/react typescript

Since react requires that we need to have a single copy of react-dom, we will be adding it as a peerDependency so that our package always uses the installing client's version. Add the following snippet to your package.json.

...
"peerDependencies": {
    "react": "^16.8.0",
    "react-dom": "^16.8.0"
 },
...

As one last step for setting up the project, let's also add a tsconfig for compiling our TypeScript. Create a file called tsconfig.json in the root and add the following to it.

{
    "compilerOptions": {
      "target": "es5",
      "outDir": "lib",
      "lib": [
        "dom",
        "dom.iterable",
        "esnext"
      ],
      "declaration": true,
      "declarationDir": "lib",
      "allowJs": true,
      "skipLibCheck": true,
      "esModuleInterop": true,
      "allowSyntheticDefaultImports": true,
      "strict": true,
      "forceConsistentCasingInFileNames": true,
      "module": "esnext",
      "moduleResolution": "node",
      "resolveJsonModule": true,
      "isolatedModules": true,
      "noEmit": true,
      "jsx": "react"
    },
    "include": [
      "src"
    ],
    "exclude": [
        "node_modules",
        "lib"
    ]
  }

These options help TypeScript to ignore and enforce certain rules while compiling our code. You can check out all the flags available in the docs.

GitHub: Code till this step

Installing Storybook

Now that we have the React boilerplate ready we can now install Storybook, run the following command in the root folder to add Storybook to your project

npx sb init

This command will install all the core devDependencies, add scripts, setup some configuration files, and create example stories for you to get you up and running with Storybook. At the time of writing this article, I am using Storybook version 6.1.9

You can now run yarn storybook and that should boot up Storybook for you with the examples they created for you.

Once you are done playing with the example, you can go ahead and safely delete the stories folder.

Now open the .storybook/main.js file. This file controls the behavior of your Storybook server by specifying the configuration for your stories.

Update the stories key in the file to this -

...
"stories": [
    "../src/**/*.stories.tsx"
 ],
...

This config would run TypeScript stories defined in the src folder, which we would be creating in the next step.

GitHub: Code till this step

Adding stories and setting up the file structure

Now that we have the Storybook setup, we can start creating our components and writing stories for them.

But first of all what are stories anyways?

Glad you asked, from the docs -

"A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support."

In short, Stories let you render the different states of your UI component and lets you play with the different states with something called Storybook Controls, which we will get to in a minute. These are development only files and hence won't be included in our final library bundle.

Let's create a demo component to check out how stories work and how you can make the most out of it.

Our file structure would look something like this -

.storybook/
  main.js
    preview.js
.gitignore
package.json
rollup.config.js
tsconfig.json
src/
    components/
      MyAwesomeComponent/
        MyAwesomeComponent.tsx
        MyAwesomeComponent.css
        MyAwesomeComponent.stories.tsx
          index.ts
  index.ts

We will be using the same button component that Storybook gave us with the demo earlier for demonstrating.

Create a folder src/components/Button and paste the Button.tsx, button.css, and index.ts files in it.

Lets add some stories ✨

Create src/components/Button/Button.stories.tsx

Now add the following default export to it -

import React from "react";
import { Meta } from "@storybook/react/types-6-0";
import Button, { ButtonProps } from "./Button";

export default {
  title: "Components/Button",
  component: Button,
} as Meta;

The default export in a story defines the meta information that will be used by Storybook and its addons.

To define a Story you need to create named exports in the file, so for example we can create a story for the primary button type like this.

export const PrimaryButton = () => <Button label="Hello world" primary />;

To simplify writing multiple stories, Storybook provides an option to create stories by defining a master template and reusing that template for each story. So in our case, the stories for Primary and Secondary type buttons can be created like this -

import React from "react";
import { Meta } from "@storybook/react/types-6-0";
import { Story } from "@storybook/react";
import { Button, ButtonProps } from "./Button";

export default {
  title: "Components/Button",
  component: Button,
} as Meta;

// Create a master template for mapping args to render the Button component
const Template: Story<ButtonProps> = (args) => <Button {...args} />;

// Reuse that template for creating different stories
export const Primary = Template.bind({});
Primary.args = { label: "Primary 😃", size: "large" };

export const Secondary = Template.bind({});
Secondary.args = { ...Primary.args, primary: false, label: "Secondary 😇" };

If you haven't already, you can restart the Storybook server by rerunning yarn storybook, and you should see the following.

Notice that Storybook automatically generated the controls, according to the component props, for us. This is thanks to react-docgen-typescript, which is used by Storybook to infer the argTypes for a component. One more reason to use TypeScript.

Apart from using auto-generated controls, you can also define custom controls for some or all props using the argTypes key. For example, let's define a custom color picker for the backgroundColor prop, replace the default export in the stories file with this -

export default {
  title: "Components/Button",
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
} as Meta;

The current story preview also looks a bit weird with the button in one corner of the preview. As one last step, add the layout: 'centered' key to the .storybook/preview.js file to center the preview. This file lets you control how your story is rendered in the Storybook.

If you followed the above steps, your final story preview would look something like this -

GitHub: Code till this step

Compiling the Library using Rollup

Now that you know how to build components with Storybook, it's time to move to the next step, which is compiling our library so that our end applications can consume it.

If you're not familiar with Rollup and wondering why we are using it to compile our library instead of something like webpack, that's because Rollup is best suited for bundling libraries, whereas webpack is suited for apps.

First, we would need to create an entry file that would export all the components for our component library. Create src/index.ts, and since our component library only has one component right now, it would look something like this -

import Button from "./components/Button";

export { Button };

Let's add rollup, run the following to install Rollup and its plugins that we'll be using to bundle the library -

yarn add --dev rollup rollup-plugin-typescript2 @rollup/plugin-commonjs @rollup/plugin-node-resolve rollup-plugin-peer-deps-external rollup-plugin-postcss postcss

Now before we add the rollup config, there are a few types of JavaScript modules that you should be aware of -

CommonJS - This the module format used by Node and webpack <2 (using the require function). Even though we are publishing a React module, we need to consider that it might also be used within an SSR (Server side rendering) environment, which generally uses Node.
ESM - This is the modern module format that we normally use in our React applications in which modules are defined using a variety of import and export statements. The main benefit of shipping ES modules is that it makes your library tree-shakable. This is supported by tools like Rollup and webpack 2+
UMD - This module format is not as popular these days. It is required when the user requires our module using a script tag.

So we would want to support both ESM and CommonJS modules for our component library so that all kinds of support tools can use it in the end application that relies on either of the module types.

To do that, package.json allows adding the entry points for both ESM and CommonJS modules via the module and main key, respectively. So add the following to keys to your package.json -

{ 
  ...
  "main": "lib/index.js",
  "module": "lib/index.esm.js",
  "types": "lib/index.d.ts",
  ...
}

The types key would point to the static types generated for your library via Rollup, which would help with IntelliSense in code editors like VSCode.

Its time to add the Rollup config file now, create a file called rollup.config.js in the root folder and add the following to it -

import peerDepsExternal from "rollup-plugin-peer-deps-external";
import resolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "rollup-plugin-typescript2";
import postcss from "rollup-plugin-postcss";

const packageJson = require("./package.json");

export default {
  input: "src/index.ts",
  output: [
    {
      file: packageJson.main,
      format: "cjs",
      sourcemap: true
    },
    {
      file: packageJson.module,
      format: "esm",
      sourcemap: true
    }
  ],
  plugins: [
    peerDepsExternal(),
    resolve(),
    commonjs(),
    typescript({ useTsconfigDeclarationDir: true }),
    postcss({
        extensions: ['.css']
    })
  ]
};

Let's break it down one by one to figure out what's happening here.

To start with, the input key indicates the entry point for Rollup for our component library, which is the index.js file that we just created, which contains the exports for all our components.

The output key indicates what types of output files will be generated at which place. As mentioned previously, we would be building the ESM and CommonJS bundles, and we read the output files for both bundles from the package.json.

Lastly there is the plugin array with which we are using the following plugins -

rollup-plugin-peer-deps-external - This plugin avoids us from bundling the peerDependencies (react and react-dom in our case) in the final bundle as these will be provided by our consumer application.
@rollup/plugin-node-resolve - This plugin includes the third-party external dependencies into our final bundle (we don't have any dependencies for this tutorial, but you'll definitely need them as your library grows).
@rollup/plugin-commonjs - This plugin enables the conversion to CJS so that they can be included in the final bundle
rollup-plugin-typescript2 - This plugin compiles the TypeScript code to JavaScript for our final bundle and generates the type declarations for the types key in package.json. The useTsconfigDeclarationDir option outputs the types to the directory specified in the tsconfig.json file.
rollup-plugin-postcss - This plugin helps include the CSS that we created as separate files in our final bundle. It does this by generating minified CSS from the *.css files and includes them via the <head> tag wherever used in our components.

Now as one last step let's add the script to build our component library, add the following script to your package.json file -

{
 ...
 "scripts": {
    ...
    "build": "rollup -c"
 },
 ...
}

Go ahead and run yarn build from your terminal and you should be able to see the lib folder created. I would recommend exploring this folder further to understand how Rollup and its plugins generate the appropriate bundles for the CommonJS and ESM modules with the type definitions.

Don't forget to add the lib folder to .gitignore.

GitHub: Code till this step

Publishing and consuming the library

Publishing the library to NPM couldn't be any easier. Since we have already defined all the required fields in package.json, you just need to run npm publish.

Once published, you should be able to import your component from your library in the consumer application just like this -

import { Button } from "my-awesome-component-library";

You can also refer to my another article for the detailed steps and best practices for publishing a library to NPM.

You might also want to keep your library private. If you have multiple projects in a monorepo and are using something like yarn workspaces, then you don't actually need to publish the package anywhere.

Place the library folder in your monorepo and add it to your workspaces array to the package.json in the root folder -

// package.json
{
  ... 
    "workspaces": [
            ...
            "my-awesome-component-library"
    ],
    ... 
}

Then you can directly access it from any other package in your workspace by just adding it as an dependency:

// my-awesome-frontend/package.json
{
  ... 
    "dependencies": {
            ...
            "my-awesome-component-library": 1.0.0,
            ...
    },
    ... 
}

Next Steps

Integrate Netlify or some other service to automatically deploy the Storybook whenever a PR is merged into master and to generate pull previews whenever a new PR is opened.
Setup test cases using React Testing library and Jest.
Add code-splitting to let the consumer application import only the required components instead of the whole library.

If this post helped you in anyway then do share it on twitter, and follow me for more.