DEV Community: Kaeden Wile

Tips to Build React Components that Devs will LOVE

Kaeden Wile — Wed, 22 May 2024 20:48:40 +0000

I lead the engineering team responsible for building our company’s design system and component library. Our components are not only seen by millions of users, they’re used by my fellow developers across dozens of repositories. After building, supporting, updating, bug fixing, and deprecating many React components with a wide audience, I’ve learned a ton of lessons and distilled my experiences into a few best practices I try to follow.

These best-practices don’t just apply to React front-end development; in fact, they’re common across software development and even engineering in general. They’re not ground-breaking, and I doubt you’ll find them shocking. But it is amazing how much of a difference keeping these simple guidelines in mind can actually make.

If you add these to your tech-design process and PR check-list, your teammates, consumers, and future self will thank you.

It all boils down to this: Simplify your API.

When I’m building a React component, my primary audience is the developer who will be using it. To give them the best experience, I need to minimize complexity. That means as I weigh all the possible ways to build a component, simplicity in the API is the most important factor.

A simple API is not the same as simple code. In fact, creating a simple API for our consumers often leads to increased complexity within our codebase, as we add additional logic behind the scenes. That’s a tradeoff we have to weigh during our tech design process.

What does it look like to create a simple API? There can be a lot of factors involved, but for React components I primarily look at:

Minimizing the total lines of code a developer has to write
Minimizing the average number of props that are used
Simplifying the types and depth of my props — i.e. using strings and numbers over objects and arrays
Matching standard HTML prop naming conventions
Eliminate edge cases with strong typing

Let’s dig into each of these.

Minimize total lines of code

This should be pretty straight-forward. In React, less code often means less complexity, although that isn’t universally true in programming. I have seen some cases where it takes 10+ lines of code to fill out the props for a simple button component, which makes it difficult and time-consuming to build even simple flows.

To help with this, I suggest avoiding redundancy and providing default values. Never use 2 props when 1 prop will do. Similarly, never use 1 prop when 0 props will do. If one prop’s value can be inferred from another, build that logic into your component. Hide the complexity behind the scenes so that your consumer doesn’t have to think about it.

Minimize the average number of props

My team builds components that are highly versatile and flexible. There are often many different ways to configure a given component, but there is one way that is the most common. I optimize for this most-common case.

Set up default behaviors and prop values so that most of the time, a developer won’t need to think about that prop at all. The holy grail is when a component can be used with no props—and it still does exactly what they need it to do.

Simplifying type and depth of props

One tempting approach to minimize the number of props is by cramming all the less common options into some catch-all prop that accepts an object. I have found that this doesn’t scale. Accepting objects for props is an anti-pattern on our team, because it’s difficult to document well and almost always creates more complexity.

I recommend using string and number types for props and moving all complexity to the children prop. There’s often a way to expose subcomponents with configuration of their own instead of accepting object or Arrays as props. It makes consumer’s code simpler to read and understand and gives them more flexibility and control.

Match HTML prop naming conventions

Naming is important in programming. With higher-quality names, we can spend less time consulting documentation. In React, we’re already working with common HTML elements that have standardized names and types. If my API matches the HTML standard, there’s less for me to document. Where it deviates, I have to document.

Our team uses object destructuring and spreading ({ ...props}) extensively to pass through standard HTML props to the component. For event handlers, we use the “on” prefix. We use “disabled” and “checked” props to match the standards on inputelements. Any time we can avoid introducing a new prop name, we keep our API surface area that much smaller.

Eliminate edge cases

Even in a simple component with just a few props, the total permutations of configuration can quickly get out of hand. My goal is to avoid the permutations that don’t make sense—for example, when “readonly” and “disabled” are set on a Button, or when “selected” is used on a non-selectable variant of Card.

We take two approaches to making these situations impossible: first, consolidating conflicting props. If “readonly”, “disabled”, and “loading” are all conflicting props on my Button, why not move them into a single “state” prop? Otherwise, when consolidation isn’t possible, we lean on TypeScript and other tooling to catch those configurations at build time.

Keep these guidelines in mind as you update and build new React components and watch how easy it is for other developers to use your components!

Hope you enjoyed!

https://wile.xyz

Make PRs the BEST PART of Programming

Kaeden Wile — Tue, 29 Nov 2022 19:07:54 +0000

In this blog post, I'd like to share some of my thoughts on how I've been able to effectively think about software development.

What I'm suggesting is not all that new--most of us do something similar already. I'm not advocating for a revolution. Rather, I hope to empower teams with a mindset the transforms the rote, painful, and mundane into something powerful and efficient.

Introducing: PRO Programming.

In our early days as developers, we often find ourselves searching for information on what to program. "Where is this type error coming from?" "How am I supposed to use this poorly documented library?" Or even, "What does this horrible JavaScript snippet actually do?" But as we mature and grow in our careers, we become more confident in writing code.

At some point we transition from thinking about what to program and begin asking how we should program. We start to ask more challenging questions, like "How can multiple developers work together on the same task?" "How do I write code changes so as to have the lowest chance of causing a production outage?" "What's the most efficient way of running a software development team?"

PRO Programming falls into this second category: it helps us know how to program, not what to program.

PRO

P.R.O. (aka Pull Request Oriented) Programming is a way to prioritize developer time and quantize the delivery of code.

The Pull Request is a developer's discrete unit of code.

On a PRO team, each developer has the following 3 priorities:
1. Top Priority: "Deliver Excellent PRs"
2. Second Priority: "Unblock teammate PRs"
3. Third Priority: "Protect the high-quality codebase"

Now let's go through and break down how each of these tenants works in practice. First off, what is a pull request?

The Pull Request is a developer's discrete unit of code.

If you've developed using git in any kind of team environment, you probably understand why everyone pushing to the main branch is a bad idea. Pull Requests (aka Merge Requests or Code Reviews, depending on your stack) are the gatekeeper for the "official" codebase, protecting against merge conflicts and silly bugs. I've yet to work on a team that doesn't use this model, where automated tests and other team members must approve your changes before they become part of the codebase.

If a developer's job is to deliver a feature, fix a bug, or to some other end modify a technical asset, the way they do it is by making a code change. Under PRO, we no longer think of Pull Requests as a necessary evil, or even just as the process by which I get my code-change in. The Pull Request is the deliverable. (Or rather, a series of pull requests is the deliverable.) Importantly, the pull request includes more than just making a code change.

Pull requests include:
1. The code change
2. The documentation
3. Comprehensive and documented testing steps
3. Evidence of all automated checks passing
4. Approval from code-owners
5. A successful merge and deployment

When I pick up a task on a PRO team, I'm not finished with that task until the Pull Request is complete. As the author, I'm responsible to make sure tests are passing, I've received approval from code-owners, and, even after merging, that the deployment was successful.

PRs may rely on one another. They must necessarily be the product of multiple developers (approvals). But at the end of the day, they are the fundamental, smallest quanta of code; and through the sum of them the codebase is built.

As a Developer, this distillation of responsibilities into the PR unit allows for the following straightforward priorities:

Deliver Excellent PRs

To be as effective as possible, a developer's primary area of focus should be the tasks they've been assigned. We don't want to get bogged down in a long review cycle, so we need to make PRs as easy to review as possible. The goal of a PR is to convince other developers that this change will improve the codebase.

Excellent PRs are:
1. As small and focused as possible
2. Well tested and documented
3. Free from bugs

Small and focused PRs are easier to develop, test, and review. Don't include any code changes that aren't directly involved in the task you're solving. Only solve one task at a time. Prioritize limiting the number of files and number of lines changed, to make it easier for reviewers. Smaller scope also makes it easier to debug and fix broken tests.

Well tested and documented PRs help reviewers now and the whole team in the future. You tested your changes; share how you tested. Explain why the change is happening and include a link to your issue tracker. That makes it easier for reviewers, and 6 months from now you'll be able to remember why you made the change.

Bug-free PRs seem like a no-brainer, but hear me out. The code review process is not a time for teammates to catch your typos. Before submitting a PR, you should code-review your own PR. Asking code-owners to catch simple bugs, syntax errors, and typos in your PR is a waste of their time and, frankly, is disrespectful.

Tip: When you ask others for PR reviews, you are presenting a finished product that is ready to be merged as soon as they approve. You should be 100% confident in the code before you ask for reviews.

Unblock teammate PRs

Few great projects are built in isolation... and still fewer projects that pay a good salary. As a team member, I am responsible for doing everything I can to unblock the PRs of my teammates. The most straightforward way of doing this is by submitting code reviews, but it's not the only way. Pair programming, team discussions, and shipping high-quality internal tooling are all important tasks as well. That said, here are a few tips on giving high-quality code reviews:

High quality code reviews are timely. When a teammate requests a code review, a code-owner should submit a review within 1 work day. I find it's easiest to have a daily routine of reviewing all open PRs. This applies both for initial reviews and for re-reviews.

Tip: It is the PR author's responsibility to request reviews. This can be tedious to request manually on every PR, but Github allows you to auto-assign reviewers.

High-quality code reviews have a certain tone to them. Writing comments in a way that is respectful, humble, and, as often as possible, open-ended, can lead to more efficient collaboration and faster code changes. Defensiveness and arguing dramatically slow down the PR process.

Reviews should look at the PR holistically, but also keep in mind the goal of limiting the scope of each PR. Don't ask for changes to things that aren't part of the original scope--opt instead for opening a tech-debt ticket. Call out changes that are too broad in scope or seem irrelevant. More small PRs are better than fewer big PRs.

Tip: If a developer repeatedly receives the same feedback on their PRs, they should discuss offline with senior team members how they can prioritize delivering excellent PRs.

Protect the high-quality codebase

The metaphor of PRs as a gatekeeper for the codebase was used earlier in this post, and it still stands. Each and every PR could be a trojan horse for debilitating technical debt. There's a balance to draw between delivering code quickly, unblocking teammates, and enforcing the high standards we have for our codebase.

Tip: PR reviews around code quality, style, and functionality can be one of the most effective ways of sharing knowledge within the team. If you don't understand something, post a comment asking a question. If the PR author made some mistake, help them understand your team's best practices.

Be a stickler. Read every line of code in a PR you approve. If you approve a PR with tech debt or a bug in it, you are just as much responsible as the author if the PR -- if not more.

Validate the functionality. A comprehensive test suite can confirm a lot of things, but it often can't confirm that a PR does what it says it will do. Manually validating the changes in a test or local environment is the best way to confirm the quality of a PR.

Automate the things humans are bad at: formatting, import sorting, unit testing, etc. IDE extensions, git hooks, and automated workflows are highly effective at this sort of task. You shouldn't ever need to post a PR comment asking someone to fix indentation or import order -- use tooling. Whether you use Github Actions, Circle CI, Travis, or something else, automated tests are vital for maintaining code quality.

The principles and best practices of PRO Programming have empowered me and the teams I'm part of to write code quickly and effectively. I hope they give you clarity and level up your teams too.

Kaeden Wile
https://wile.xyz

The Best Way To Build Big React Components 🤯

Kaeden Wile — Mon, 31 Oct 2022 16:30:00 +0000

With my current development team, I'm building a reusable react component library. Some of these components, like our <Button/>, are fairly simple. I can easily expose all the Button's options and functionalities through its props. Something like this:

<Button
    id="my-cool-button"
    onClick={() => console.log("I got clicked!")}
    variant="secondary"
    disabled={false}
    size="large">
    Press Me!
</Button>

But even for such a simple example, we end up with quite a few lines of code. This problem of having too many props gets far more dramatic when we begin looking at complex "composed-components" which are made up of many different pieces.

Take, for example, the <Modal/>. Our design includes: a header with multiple configurations including primary title, subtitle, a hero image, and/or a close button; a call-to-action footer allowing a variable number of buttons in different layouts; and a primary content section. In addition to the standard props of each Text, Image, and Button component for all of these items, our consumers have asked for the ability to do additional layout and style customization.

That's a lot of props!

There has to be a better way to do this -- and there is! This blog post aims to cover the solution that our team has taken in answering the following question:

How can we build "composed-components" to provide default styles, customizability, and a clean API?

And how to do you do it all in TypeScript? 😉

The Problem

First, let's dig a little deeper into exactly what we want to accomplish.

To start consuming our library, all a team has to do is yarn add "our-react-library" and import { Component } from "our-react-library";. Most developers won't ever look at our code; instead, they'll browse component documentation in our interactive Storybook. As we prioritize ease-of-use, we want all of our components to look great out of the box.

In addition to a React library, our team also publishes global design standards and a design component library for use across the company. However, there are often edge cases or situations where a team wants to make tweaks or changes. Those are easy enough to approve in design, but often require us to expose many layers of classNames (eww) or add even more props in React. Our solution for the modal needs to support multiple variants, but avoid introducing an ungainly number of props.

Finally, we always want to provide a great developer experience -- that means delivering an API that allows our users to write clean, concise code. Using long component names like ModalPrimaryTitle or polluting our package namespace with generic PrimaryTitle aren't acceptable solutions. Neither is using nested objects as props to hide config or options, which is difficult to document and doesn't work well with Storybook. And of course, we want to build TypeScript-first 🦸‍♂️.

The Process

I started this journey with our old modal, which had a lot of props and still was very challenging to customize. And, the new design our team came up with included more options and flexibility than before.

We knew very early on that we wanted to avoid any solution that was too prop-heavy, which pushed us towards exposing multiple elements to the user. Something like this:

<Modal>
    <h1>Main Title</h1>
    <h2>Subtitle</h2>
    {bodyContent}
    <button>CTA 1</button>
</Modal>

One early suggestion was to update our code-snippet generator in Storybook to return raw HTML that looked like a modal, so we didn't even need to make a component. But, that solution would detach our consumers code from our library, rendering us unable to push new features or fixes without them updating their code. It would also be difficult to style, because we used styled-components instead of relying on class names or bundling a stylesheet.

Still, we liked the direction we were headed in. The next suggestion was to provide a simple Modal that acted as a container, allowing users to pass our other existing components into it. But the layout was too complex to tackle without additional wrappers for the header and footer, so we added those which gave us greater customizability.

import {
    Modal,
    ModalHeader,
    ModalContent,
    ModalFooter,
    Text,
    Button
} from "our-react-library";

<Modal>
    <ModalHeader>
        <Text as={"h1"} size={6} weight={"bold"}>Main Title</Text>
        <Text as={h2} size={4}>Subtitle</Subtitle>
    <ModalHeader>
    <ModalContent>
        {bodyContent}
    </ModalContent>
    <ModalFooter>
        <Button 
            variant={"primary"}
            size={"large"}
            onClick={() => console.log("Clicked!")}
        />
            Go forth and prosper
        </Button>
    </ModalFooter>
</Modal>

This is looking better, but it still had a few issues. Namely, we were (1) asking our users to manually apply default styles to the title, subtitle, call to action buttons, and more; and (2) we were polluting our namespace with lots of Modal-specific components. The solution to the 1st problem is easy, but it exasperates the second problem: introduce a ModalTitle component, a ModalSubtitle component, a ModalCTA component, etc. Now if we can just find a simple place to put all those pesky components, we would have a pretty good solution!

What if we put the sub-components on Modal itself?

The Solution

Below is the API we decided on. Every component matches our design out of the box, but also allows for customization using CSS classes or styled-components. Adding or removing full sections or adding custom components anywhere in the flow is fully supported. The API is clean and concise and ~~most importantly~~ the namespace is immaculate.

import { Modal } from "our-react-library";

<Modal>
    <Modal.Header>
        <Modal.Title>Main Title</Modal.Title>
        <Modal.Subtitle>Subtitle</Modal.Subtitle>
    </Modal.Header>
    <Modal.Content>
        This is my body content
    </Modal.Content>
    <Modal.Footer>
        <Modal.CTA>Click me!</Modal.CTA>
    </Modal.Footer>
</Modal>

Now I know what you're thinking, "That looks great, but how can you make that work in TypeScript?"

I'm glad you asked.

We use React functional components to build most of our library, so inside the library, our files look something like this:

export const Button = ({ children, size, ...props}: ButtonProps): JSX.Element => {
    if (size === "jumbo") {...}

    return (
        <StyledButton size={size} {...props}>
            {children}
        </StyledButton>
    );
}

TypeScript, however, does not allow us to assign additional props to a const, especially after we export it. This poses a problem. Somehow we have to attach props to what is essentially a function without writing a ton of duplicate code. Another pesky problem is setting correct displayNames for React DevTools and, more importantly, our Storybook code generator.

Here's the magic function:

import React from 'react';

/**
 * Attaches subcomponents to a parent component for use in
 * composed components. Example:
 * 
 * <Parent>
 *    <Parent.Title>abc</Parent.Title>
 *    <Parent.Body prop1="foobar"/>
 * </Parent>
 * 
 *
 * This function also sets displayname on the parent component
 * and all children component, and has the correct return type
 * for typescript.
 *
 * @param displayName topLevelComponent's displayName
 * @param topLevelComponent the parent element of the composed component
 * @param otherComponents an object of child components (keys are the names of the child components)
 * @returns the top level component with otherComponents as static properties
 */
export function attachSubComponents<
  C extends React.ComponentType,
  O extends Record<string, React.ComponentType>
>(displayName: string, topLevelComponent: C, otherComponents: O): C & O {
  topLevelComponent.displayName = displayName;
  Object.values(otherComponents).forEach(
    (component) =>
      (component.displayName = `${displayName}.${component.displayName}`)
  );

  return Object.assign(topLevelComponent, otherComponents);
}

The above code lives in a util file and can easily be imported within our library any time we want to use sub-components. That allows us to write a modal component file that is very easy on the eyes:

export const Modal = attachSubComponents(
    "Modal",
    (props: ModalProps) => { ... },
    { Header, Content, Footer, Title, Subtitle, HeroImage, ... }
);

And best of all, it's a great solution for all of our users!

Thanks for reading! I hope this technique for creating clean composed components in React will level-up you and your team.

Kaeden Wile
wile.xyz