---
title: Type safe, auto-generating test data for API mocking
description:
  How to efficiently generate valid, type safe, realistic data for use in
  automated testing
image: benjamin-voros-phIFdC6lA4E-unsplash.webp
date: '2025-04-05'
---

> This article is part 2 in a series. Part 1
> ([No more trust me bro data fetching](/post/no-more-trust-me-bro-data-fetching))
> covers how to use Zod (or similar validation libraries) to tightly couple both
> runtime and build time data validation. Part 2 continues with using these data
> schemas to help mock APIs when authoring automated tests.

## Avoid flake, mock the backend

When automating application testing, managing the state of the backend in a
manner that is consistent and avoids flakiness is exceptionally difficult. To
address this problem, decoupled frontend user interfaces are often tested with a
mocked backend, intercepting HTTP requests in the browser and replacing their
responses with mock data.

- See [fixtures using Cypress.io](https://docs.cypress.io/api/commands/fixture)
- See [API mocking using Playwright](https://playwright.dev/docs/mock)

For the sake of simplicity, the rest of the examples in this post will use
[Playwright](https://playwright.dev/). This is the end result we will be
building towards &mdash; a rendered UI that fetches data from a mocked API
response:

```ts
import { test, expect, chromium } from '@playwright/test'
import { generateMock } from '@anatine/zod-mock'
import { z } from 'zod'
import { AccountSchema } from '../src/api'

const mockAccountList = generateMock(z.array(AccountSchema), { seed: 123 })

test('it shows accounts', async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 200 })
  const context = await browser.newContext()
  const page = await context.newPage()

  // Mock the accounts API
  await page.route(
    'https://api.nicklemmon.com/accounts/list',
    async (route) => await route.fulfill({ json: mockAccountList })
  )

  // Visit the accounts page
  await page.goto('http://localhost:5173')

  // Validate the rendered result
  await expect(page.getByRole('heading', { name: 'Accounts' })).toBeVisible()
  await expect(page.getByText('Jane Turcotte / 471649368545782')).toBeVisible()
})
```

## Validating the backend

First, let's author some Zod schemas to validate the JSON response that will be
received from the backend. This example is directly from the prior article in
the series,
[“No more &lsquo;Trust me, bro&rsquo; data fetching in TypeScript applications”](/post/no-more-trust-me-bro-data-fetching).

Let's say that our `/accounts/list` endpoint returns a list of accounts. We can
validate that data at runtime using a library like `zod` to double check its
shape, and handle errors if an unexpected response is returned:

```ts
import { z } from 'zod'

// 👇 this is our schema defined with Zod (available at runtime)
const AccountSchema = z.object({
  id: z.string(),
  name: z.string(),
  holdings: z.number(),
})

// 👇 this is our type definition inferred from the Zod schema (available at build time)
type Account = z.infer<typeof AccountSchema>

export async function listAccounts() {
  const res = await fetch('https://api.nicklemmon.com/accounts/list')

  try {
    if (!res.ok) throw Error('Account fetching failed!')

    const json = z.array(AccountSchema).parse(await res.json())

    return json
  } catch (err) {
    throw Error(String(err))
  }
}
```

With our Zod schema defined, we can avoid a large category of type errors at
runtime, or at the very least, be well equipped to monitor our application for
data consistency errors.

## Building a UI

In this example, we will use our `listAccounts` function to fetch data in a
frontend single page application. Let's take a look at how this would work in a
React application (and use some of their newer features while we're at it). In
this example,
[@tanstack/react-query](https://tanstack.com/query/latest/docs/framework/react/quick-start).

```tsx
import {
  useQuery,
  useQueryClient,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
// 👇 Here, we import our `listAccounts` function with baked-in zod validation
import { listAccounts, type Account } from './api'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Normally a router would be used here, but for the sake of simplicity we are using a component */}
      <AccountsPage />
    </QueryClientProvider>
  )
}

function AccountsPage() {
  // 👇 Our query fetches (and caches) the data as soon as the component mounts
  // Note that generics are used here to help with type inference. Since the `Account`
  // type definition is directly derived from our Zod schema, this is considered safe
  const { data, isLoading } = useQuery<Array<Account>>({
    queryKey: ['accounts'],
    queryFn: listAccounts,
  })

  return (
    <div>
      <h1>My accounts</h1>

      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <ul>
          {data?.map((account) => {
            return (
              <li key={account.id}>
                {account.name} / {account.holdings}
              </li>
            )
          })}
        </ul>
      )}
    </div>
  )
}
```

## Mocking the backend

Our UI is built, our data is fetching, now we want to mock the data. Since we
have already used zod to validate our API response, we can _automatically create
mock test data using our zod schema_!

First, let's install
[@anatine/zod-mock](https://www.npmjs.com/package/@anatine/zod-mock) to create
fake test data generated directly from our Zod schemas:

```bash
npm i @anatine/zod-mock -D -E
```

We can then derive mock data from our schema in our test case without having to
manually author mocks. This allows mocks and source code to always stay in sync
&mdash; when our schemas change, our mocks update seamlessly.

```ts
import { test, expect, chromium } from '@playwright/test'
import { generateMock } from '@anatine/zod-mock'
import { z } from 'zod'
import { AccountSchema } from '../src/api'

// Generate mock account list from our zod schema
// Note we are using a seed here to force the account list to remain consistent for every test run and make sure it is deterministic,
// otherwise the test case will fail as the mock data will change each time the test runs
const mockAccountList = generateMock(z.array(AccountSchema), { seed: 123 })

test('it shows accounts', async () => {
  const browser = await chromium.launch({ headless: false, slowMo: 200 })
  const context = await browser.newContext()
  const page = await context.newPage()

  // Mock the accounts API
  await page.route(
    'https://api.nicklemmon.com/accounts/list',
    async (route) => await route.fulfill({ json: mockAccountList })
  )

  // Visit the accounts page
  await page.goto('http://localhost:5173')

  // Validate the rendered result
  await expect(page.getByRole('heading', { name: 'Accounts' })).toBeVisible()
  await expect(page.getByText('Jane Turcotte / 471649368545782')).toBeVisible()
})
```

## Putting it all together

Take a look at the
[GitHub repo showing this example](https://github.com/nicklemmon/blog-type-safe-data-mocking),
install the dependencies, and run the tests. The test cases launch and mock the
accounts API, showing generated data in its place.

```bash
git clone https://github.com/nicklemmon/blog-type-safe-data-mocking.git
cd blog-type-safe-data-mocking
npm run dev &
npx wait-on http://localhost:5173
npm run test
```


How to efficiently generate valid, type safe, realistic data for use in automated testing

Type safe, auto-generating test data for API mocking

---
title: No more “Trust me, bro” data fetching in TypeScript applications
description: Validate fetched data at runtime and build time
image: marek-piwnicki-HxPkohFqDGY-unsplash.webp
date: '2025-03-03'
---

TypeScript can help prevent a whole category of software defects, ensuring data
flows smoothly and predictably throughout an application &mdash; I have no idea
how I built applications without it in the past. When used insufficiently,
however, TypeScript does not offer this protection &mdash; rather, application
teams need to invest in adequate type safety, particularly when fetching data
&mdash; all while avoiding the temptation to tell the TypeScript compiler,
"trust me, bro."

> This is the first article in a series about predictable, type-safe data
> fetching in TypeScript applications. In part one, I will be covering common
> type checking failures when fetching data. In part two, I'll explore automated
> integration testing strategies that work well with type-safe data fetching.

## “Trust me, bro” data fetching

When fetching data, the JSON response is never typed by default, as the inferred
type of a typical fetching function is `Promise<any>`:

```ts
async function listAccounts() {
  const res = await fetch('https://api.nicklemmon.com/accounts/list')

  if (!res.ok) throw Error('Account fetching failed!')

  return await res.json() // 👈 The inferred return type is `Promise<any>`
}
```

In typical applications, this problem is addressed via a type assertion using
`as`. When using `as` in this scenario, this is a "trust me, bro" moment. The
developer is telling the TypeScript compiler to not worry about the shape of the
response &mdash; "Trust me, bro," the shape is _always exactly what I say it
is_. No need to check yourself, TypeScript!

```ts
type Account = {
  id: string
  name: string
  holdings: number
}

async function listAccounts() {
  const res = await fetch('https://api.nicklemmon.com/accounts/list')

  if (!res.ok) throw Error('Account fetching failed!')

  // Here is the type assertion 👇
  // "Trust me, bro! The response is definitely an array of accounts."
  return (await res.json()) as Array<Account>
}
```

At this point, the data you receive could come in _any_ shape, and by using
`as`, we have simply turned off any adequate protection that TypeScript might
provide when it comes to the shape of the data flowing throughout our
application.

Even fully fledged, popular frontend frameworks (like Angular), who expose a
service for data fetching (see the
[HttpClient documentation for more](https://angular.dev/guide/http/making-requests#fetching-json-data)),
still handle data typing via the "trust me, bro" strategy out of the box. In
this case, a generic is used instead of a type assertion, but the end result is
the same.

```ts
// This isn't using `as`, but a generic - the end result is the same - the shape of the data is not validated at runtime but is assumed!
// "Trust me, bro! The account list is *always* in the right shape!"
http.get<Array<Account>>('https://api.nicklemmon.com/accounts/list')
```

Unfortunately, this leaves a lot to be desired. If the shape of the API response
ever changes unexpectedly _or_ if the type definition of `Account` is
inaccurate, any application logic that assumes the return type of
`listAccounts()` is `Array<Account>` can _never_ be completely trusted. Even
though TypeScript is used in the data fetching function, runtime errors can and
will occur unpredictably over time.

## Actually type safe (and predictable) data fetching

Instead of blindly assuming that your data is shaped in a certain way, it is
best to first validate that data at runtime, typically using a schema validation
library like [zod](https://zod.dev/) or [valibot](https://valibot.dev/).

Let's re-write our `listAccounts` function to validate the shape of the response
using `zod`:

```ts
import { z } from 'zod'

// This feels similar to TypeScript, but available at runtime
const AccountSchema = z.object({
  id: z.string(),
  name: z.string(),
  holdings: z.number(),
})

async function listAccounts() {
  const res = await fetch('https://api.nicklemmon.com/accounts/list')

  try {
    if (!res.ok) throw Error('Account fetching failed!')

    // We `.parse` the awaited JSON response to ensure its in the right shape,
    // and catch any errors that might result. With a monitoring service in place,
    // we could flag type runtime errors more cleanly for fixing by API teams.
    const json = AccountSchema.parse(await res.json())

    return json // The inferred return type will match the shape of the `AccountSchema`
  } catch (err) {
    throw Error(String(err))
  }
}
```

The `AccountSchema` looks awfully similar to TypeScript, but with a few extra
lines we can have both a schema definition which can handle validation at
runtime _and_ a type definition at build time which are inherently linked:

```ts
import { z } from 'zod'

// Runtime schema
const AccountSchema = z.object({
  id: z.string(),
  name: z.string(),
  holdings: z.number(),
})

// Build time type definition
type Account = z.infer<typeof AccountSchema>
```

Now we can have type safe data fetching with type definitions _and_ runtime type
validation &mdash; all of which are tightly coupled to produce predictable
results.

## Schema and type usage in the UI layer

Now that we have a defined type, our UI can fetch data, and then render the
result predictably, all while passing the data down the component tree safely.
The following example uses [TanStack Router](https://tanstack.com/router/latest)
and React to help orchestrate fetching and rendering.

First, we define our route. We can import our `listAccounts` function and use it
in the route definition:

```tsx
import { createFileRoute } from '@tanstack/react-router'
import { listAccounts } from '../api'

export const Route = createFileRoute('/accounts/$list')({
  component: RouteComponent,
  loader: async () => {
    // Remember, this function validates the shape of the data
    // or throws an error if the data is in an unexpected shape
    return await listAccounts()
  },
})

function RouteComponent() {
  // The account list is made available through the baked-in `useLoaderData` hook
  const accountList = Route.useLoaderData()

  return <h1>List of accounts</h1>
}
```

Additionally, we can define an `<AccountListTable />` component, which expects
an `accountList` as a prop:

```tsx
import type { Account } from '../api'

function AccountListTable({ accountList }: { accountList: Array<Account> }) {
  return (
    <table>{/* Logic for rendering the account list table goes here */}</table>
  )
}
```

We can then render the `<AccountListTable />` in our accounts list route,
achieving end-to-end type safety, without relying on "trust me, bro" TypeScript
techniques. The shape of our API response may change unexpectedly, but error
handling will more catch errors at their source, making them dramatically easier
to debug.

```tsx
import { createFileRoute } from '@tanstack/react-router'
import { listAccounts } from '../api.ts'
import { AccountListTable } from '../account-list-table.tsx'

export const Route = createFileRoute('/accounts/$list')({
  component: RouteComponent,
  loader: async () => {
    // Remember, this function validates the shape of the data
    // or throws an error if the data is in an unexpected shape
    return await listAccounts()
  },
})

function RouteComponent() {
  // The account list is made available through the baked-in `useLoaderData` hook
  const accountList = Route.useLoaderData()

  return (
    <div>
      <h1>List of accounts</h1>

      {/* Ta-dah! The inferred type from the `listAccounts` function matches the expected type defined explicitly in the <AccountListTable /> */}
      <AccountListTable accountList={accountList} />
    </div>
  )
}
```

## Conclusion

`zod` (and other similar tools, like [valibot](https://valibot.dev)) provide a
protective layer against unexpected data shapes in TypeScript applications,
improving the predictability and reliability of application code, all while
avoiding the "trust me, bro" mistakes that are common when handling data
fetching.

> This is the first article in a series about predictable, type-safe data
> fetching in TypeScript applications. In part two, I'll explore automated
> integration testing strategies that work well with type-safe data fetching.


Validate fetched data at runtime and build time

No more “Trust me, bro” data fetching in TypeScript applications

---
title: Use string unions, not enums in TypeScript
description: Prefer string unions over enums in TypeScript projects!
date: '2025-02-08'
image: janosch-diggelmann-ZxlAVtQjcpI-unsplash.webp
---

[Enums](https://www.typescriptlang.org/docs/handbook/enums.html) in TypeScript
are a language feature that should generally be avoided &mdash; instead, use
string unions for most use cases. Ultimately, string unions are simpler to both
use and implement, allowing for end-to-end type safety without sacrificing
developer experience.

Often used for things like prop types or function parameters, an enum can be
used to define a union of possible acceptable values.

```tsx
enum Variant {
  Primary = 'primary',
  Secondary = 'secondary',
  Destructive = 'destructive',
}

function MyButton({ variant }: { variant: Variant }) {
  let className

  if (variant === Variant.Primary) {
    className = 'primary-btn'
  }

  if (variant === Variant.Secondary) {
    className = 'secondary-btn'
  }

  if (variant === Variant.Destructive) {
    className = 'destructive-btn'
  }

  return <button className={className}>Click me</button>
}
```

In this (fairly contrived) example, the enum is used to determine which CSS
class should be applied to the button. This solution works for defining several
valid variants (and excluding all others), but it offers worse developer
ergonomics over time than alternative approaches.

## Enum problems

### 1. Enums do not exist in JavaScript at runtime

By the time TypeScript compiles, the JavaScript engine running your program no
longer has a reference to the enum in a true 1 to 1 sense. As a result,
[an enum becomes an object at runtime](https://www.typescriptlang.org/docs/handbook/enums.html#enums-at-runtime).
This isn't necessarily a _problem_ but it can be confusing, particularly to
developers who may not be aware that all constructs in TypeScript do not map
one-to-one to JavaScript constructs.

Enums
[can have surprising differences](https://www.totaltypescript.com/why-i-dont-like-typescript-enums)
once compiled to JavaScript!

### 2. Enums add to bundle size

Because an `enum` must be imported and used as a value, it must be available at
runtime, adding to overall bundle size once compiled.

```ts
// This creates `VariantEnum` at runtime
enum Variant {
  Primary = 'primary',
  Secondary = 'secondary',
  Destructive = 'destructive',
}
```

```ts
// This is not available at runtime at all
type Variant = 'primary' | 'secondary' | 'destructive'
```

### 3. More boilerplate when passing enums to functions/components

When we use an enum to strictly type a function (or component props), developers
have to import that enum in order to use it when invoking the function (or
component), adding additional overhead that isn't required when using string
unions.

To take the previous example, let's use our `MyButton` component and pass a
variant:

```tsx
import { Variant, MyButton } from './my-button.tsx'

function MyPage() {
  return <MyButton variant={Variant.Primary} />
}
```

This is relatively painless in a React application, but when used in an Angular
component, things get a little unusual

#### Angular component props and enums

In this example, we define our `enum` (just like in the React `MyButton`
component) but there is a _lot_ more boilerplate required to implement the end
result.

```ts
import { Component, Input } from '@angular/core'
import { NgClass } from '@angular/common'

enum Variant {
  Primary = 'primary',
  Secondary = 'secondary',
  Destructive = 'destructive',
}

@Component({
  selector: 'my-button',
  imports: [NgClass],
  template: `
    <button
      [ngClass]="{
        primary: this.variant === this.Variant.Primary,
        secondary: this.variant === this.Variant.Secondary,
        destructive: this.variant === this.Variant.Destructive,
      }"
    >
      Click me
    </button>
  `,
})
export class MyButton {
  public Variant = Variant

  @Input()
  variant?: Variant
}
```

This works fairly cleanly when defining the component, though we do have to
expose the `Variant` enum has a public member of the `MyButton` class in order
to use it. Not only that, but we have to import and expose the `Variant` in each
component class that uses the button `variant` prop! That is a _lot_ of code to
pass a string.

```ts
import { Component } from '@angular/core'
import { MyButton, Variant } from './my-button'

@Component({
  selector: 'my-page',
  imports: [MyButton],
  template: `<my-button [variant]="this.Variant.Primary"></my-button>`,
})
export class MyPage {
  // 😥 exposing this to access it in the template
  public Variant = Variant
}
```

Not to mention, now the `MyPage` class exposes a public `Variant` that can be
accessed programmatically &mdash; and without a significant benefit since our
intention was only to leverage the value in the component template.

## String unions as an alternative

For most enum use cases, use string unions instead. This simplifies both our
prior React and Angular button examples substantially.

### React example

First, the button component.

```tsx
type Variant = 'primary' | 'secondary' | 'destructive'

// We can do a nice little look up here with each object key
// strictly typed to be a valid `Variant`
const VARIANT_CLASS_MAP: Record<Variant, string> = {
  primary: 'primary-btn',
  secondary: 'secondary-btn',
  destructive: 'destructive-btn',
}

function Button({ variant }: { variant: Variant }) {
  return <button className={VARIANT_CLASS_MAP[variant]}>Click me</button>
}
```

And now its usage.

```tsx
import { Button } from './my-button'

function MyPage() {
  // No need to import `Variant` at all!
  // *And* TypeScript will still throw an error at build time with an invalid value
  return <Button variant="primary" />
}
```

### Angular example

First, the button component.

```ts
import { Component, Input } from '@angular/core'
import { NgClass } from '@angular/common'

type Variant = 'primary' | 'secondary' | 'destructive'

@Component({
  selector: 'my-button',
  imports: [NgClass],
  template: `
    <button
      [ngClass]="{
        primary: this.variant === 'primary',
        secondary: this.variant === 'secondary',
        destructive: this.variant === 'destructive',
      }"
    >
      Click me
    </button>
  `,
})
export class MyButton {
  @Input()
  variant?: Variant
}
```

And now its usage:

```ts
import { Component } from '@angular/core'
import { MyButton } from './my-button'

@Component({
  selector: 'my-page',
  imports: [MyButton],
  template: `<my-button variant="primary"></my-button>`,
})
export class MyPage {}
```

### String unions at runtime

At times, string union values need to be made available at runtime. To achieve
this (and avoid repetition), define the string union values in a constant array
and derive the `type` from said array.

```ts
const VARIANTS = ['primary', 'secondary', 'destructive'] as const

type Variant = (typeof VARIANTS)[number]
```

It then becomes trivial to write a type guard function if needed using the same
constant array.

```ts
function isVariant(arg: any): arg is Variant {
  return VARIANTS.includes(arg)
}
```

### When you just can't quit enumerating

If you still insist on using enums (or need to refactor an existing codebase
that uses enums heavily), consider defining the enum `as const` which can help
avoid some of the aforementioned problems outlined in this article.

See more
[from Matt Pocock via Total TypeScript essentials](https://www.totaltypescript.com/books/total-typescript-essentials/deriving-types#using-as-const-for-javascript-style-enums).

## Conclusion

String unions are capable alternatives to TypeScript enums in most scenarios,
and enable improved developer ergonomics and simplified implementation
particularly when defining function parameters or component props (especially
Angular component props!). While enums still _can_ be used, string unions should
be used in their place in most circumstances.


Prefer string unions over enums in TypeScript projects!

Use string unions, not enums in TypeScript

---
title: Inversion of control in design systems
description:
  Encouraging component composition, avoiding overly complex component
  maintenance, and empowering teams
date: '2025-01-23'
image: 'omar-flores-lQT_bOWtysE-unsplash.webp'
---

## The promise of design systems

UI component libraries and design systems enable brand consistency at scale. By
leveraging a design system, large organizations can ship consistently branded
digital experiences without the need to re-build repetitive UI elements across
multiple applications simultaneously.

Designers and engineers on a design system team may view a component library as
a means of establishing visual and logical control over disparate teams and
processes, narrowing the range of possibilities that can be produced across a
large digital footprint.

For example, the component may include some opinions about where icons can be
placed. In our initial draft, we built a button component that accepts an `icon`
prop:

### A simple problem: a button with an icon

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return <Button icon="plus-circle">Click me</Button>
}
```

> Designers and engineers on a design system team may view a component library
> as a means of establishing visual and logical control over disparate teams and
> processes, narrowing the range of possibilities that can be produced across a
> large digital footprint.

Ta-dah! In this example, the `Button` handles the icon via a unique identifier,
rendering it on the right hand side of the element only. Now we can _require_
teams within our company to only position icons on the right and make sure we
keep our buttons visually consistent across applications.

### Fix #1

Unfortunately, we immediately get a request to support icons on the left &mdash;
and the requesting team has a very strong argument for doing so that we never
could have anticipated when we first started. How can we handle this without
publishing a breaking change to our component? Maybe the better original
component API would have looked something like this:

```tsx
import { Button } from '@company/ui'

function MyApp() {
  // `iconPosition` can be "right" or "left", defaulting to "right" when nothing is set
  return (
    <Button icon="plus-circle" iconPosition="left">
      Click me
    </Button>
  )
}
```

Ta-dah! We did it. Now we have solved our problem and we can ride in to the
sunset truly and confidently victorious. We do have two separate props that are
tightly coupled, but at least they both start with the name `icon` so that
shouldn't be too painful...

### Fix #2 (not again)

Once again we receive a request from a team building an application &mdash; and
they really need **two icons at once**, one icon on each side _simultaneously_.
Well, this will be difficult to support with our existing component API but
let's roll up our sleeves and give it a shot.

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* We still need to support our old API, so let's leave this as an example of what that looks like */}
      <Button icon="plus-circle" iconPosition="left">
        Click me
      </Button>
      {/* We can also support this newer approach (definitely bulletproof this time!) */}
      <Button rightIcon="plus-circle" leftIcon="checkmark">
        Click me
      </Button>
    </>
  )
}
```

I'm not sure what would happen if an engineer tried to use `iconPosition` and
`leftIcon` at the same time, but surely no one would do something so foolish,
right?

### Fix #3 (It won't stop)

After declaring victory, we ride in to the sunset. At least until another team
requests our help with the `Button` component. This time they aren't too
concerned with `iconPosition`, but they do want to change the color of the icon
somehow &mdash; and ideally they could use a design token to do so.

Well, that shouldn't be too hard (though we do have to support all of our
existing component API surface when we make this change):

```tsx
import { Button } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* Well, `iconColor` will work here but we definitely can't have two different colors at once */}
      <Button icon="plus-circle" iconPosition="left" iconColor="fg.action">
        Click me
      </Button>
      {/* Aha! We *can* support two different colors with this API though */}
      <Button
        rightIcon="plus-circle"
        leftIcon="checkmark"
        rightIconColor="fg.action"
        leftIconColor="fg.success"
      >
        Click me
      </Button>
    </>
  )
}
```

> What started with good intentions (control over design) has quickly devolved
> in to a mess for the engineering team, all without any material benefit with
> regards to design consistency and standardization.

Well, we made the consuming team happy but this is getting really gnarly and
hard to maintain. In order to support icons in two positions, each with distinct
imagery and color, we now have _7 props we need to maintain_ &mdash; and nearly
all of them are tightly coupled with one another, meaning each time we need to
change 1 we put the other 6 at risk of a break. Not good.

Not to mention, the design team's goal of controlling the visual positioning of
icons within buttons has now been lost. Now we have lost consistency _and_ we
have a highly complex component simultaneously. What a mess.

What started with good intentions (control over design) has quickly devolved in
to a mess for the engineering team, all without any material benefit with
regards to design consistency and standardization.

## Enter component composition and inversion of control

Looking from the end result, it's easy to see how a component API like this can
naturally evolve over time and end in a unenviable place. A rather simple
component that accepts an icon is now extremely complex and brittle to maintain.
If we could hop in a time machine, how could we have handled this better?

### Children/slots and the compound component

Instead of using string props, it's time to use `children` (in some other
frameworks this might be content projection or a `slot`) to make the component
surface area much smaller while keeping everyone happy (especially the design
system engineering team):

```tsx
import { Button, ButtonIcon } from '@company/ui'

function MyApp() {
  return (
    <>
      {/* To reposition the icon, we just put it first in the DOM order just like regular HTML */}
      <Button>
        <ButtonIcon icon="plus-circled" />
        Click me
      </Button>
      {/* And here is the same icon on the right */}
      <Button>
        Click me
        <ButtonIcon icon="plus-circled" />
      </Button>
      {/* And now one icon on each side */}
      <Button>
        <ButtonIcon icon="success" />
        Click me
        <ButtonIcon icon="plus-circled" />
      </Button>
      {/* And now each icon has its own color */}
      <Button>
        <ButtonIcon icon="success" color="fg.success" />
        Click me
        <ButtonIcon icon="plus-circled" color="fg.action" />
      </Button>
    </>
  )
}
```

Success! We have accomplished a few things with this approach:

1. We have decoupled props &mdash; the `ButtonIcon` component has its own props
   that control its appearance, but they are distinct from the parent `Button`
2. Teams can implement icons in whichever order they choose in an
   easy-to-understand way, no component API documentation required
3. The `Button` component is much less likely to break accidentally when its
   internal structure changes compared to the old approach
4. Teams can even use conditional logic within a button instance more easily,
   using JSX to conditionally add and remove icons based on conditions relevant
   to their users

### Empowerment over top-down control

By empowering application teams to better serve the needs of their users, design
system teams can build components with a much better developer experience all
while reducing the risk of regression defects in the future. Teams may build
wild and crazy things using their newfound power of component composition
&mdash; and at the end of the day that's OK. Application teams are _almost
always closer to their users and the needs of the business_ and giving
application teams the keys to their own destiny is the only way to effectively
build a design system at scale

## Learn more

Inversion of control, component composition, and compound components are not new
ideas, yet many design systems still fail to empower their application teams to
build high quality digital products by inverting (giving up) control.

If you are having trouble taking the component composition high road (or
convincing others to do the same), read through some helpful articles on the
subject from industry experts to learn more about the how of the approach:

- [Inversion of Control by Kent C. Dodds](https://kentcdodds.com/blog/inversion-of-control)
- [Compound Components by Ryan Florence](https://www.youtube.com/watch?v=hEGg-3pIHlE)
- [Compound Components by Kyle Shevlin](https://kyleshevlin.com/compound-components/)


Encouraging component composition, avoiding overly complex component maintenance, and empowering teams

A frontend engineering leader driven to create accessible user interfaces at scale.

The latest

Type safe, auto-generating test data for API mocking

No more “Trust me, bro” data fetching in TypeScript applications

Use string unions, not enums in TypeScript

Inversion of control in design systems