---
title: Staff-level engineering with AI agents
description: Using AI agents to effect product change - not just lines of code.
date: '2026-01-13'
image: 'jakub-zerdzicki-UaylYFMAhWk-unsplash.webp'
---

AI agents are rapidly changing the landscape of software engineering as a craft,
increasing developer productivity, and empowering smaller teams to ship at a
higher velocity. When less skilled and experienced engineers leverage agents,
results can be mixed, resulting in a much higher volume of code output without
positively impacting the end product.

Fortunately, many of the standard continuous integration and delivery techniques
leveraged by senior and staff-level engineers can be applied to dramatically
increase the success of agentic workflows. Fortunately, there are key strategies
and techniques that software engineers can lean on to get more out of their AI
partners.

### Strategies

#### 1. Write prompts in a markdown format

Prompts with structured content convey additional meaning that words alone miss.
[AI works well with markdown](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/),
so leverage markdown syntax to structure and organize directions.

Complex instructions, for example, can be contained entirely within a markdown
file (something like `INSTRUCTIONS.md`)

#### 2. Keep scope constrained

When prompting an AI agent, much like a human, keep the scope of a task
constrained. Clearly scoped, small tasks increase the likelihood of success for
both AI agents and human engineers. For example:

```txt
Implement three new automated QA checks to the project, installing necessary
dependencies and adding them to the CI/CD pipeline.
```

This prompt is _very_ broad. Which QA checks is the prompter interested in
adding? Are all QA checks of equal value? _How_ should these be integrated into
the CI/CD pipeline for the project? Do these run on every push of every branch
or in some other scenario?

> A human providing a poorly scoped prompt is likely to be disappointed with the
> agent's results

A human providing a poorly scoped prompt is likely to be disappointed with the
agent's results due to the overly broad scope of the requirements. Instead, be
specific and tackle one task at a time:

```txt
Configure ESLint for this project and be sure to handle the TypeScript plugin
according to the current `tsconfig.json` for the project. Integrate this script
into the CI/CD pipeline to run on every new pull request and on the `main`
branch.
```

The second prompt **keeps the scope constrained** to a single tool **with
specific instructions** for implementation.

#### 3. Provide clear requirements

In addition to narrowing scope, provide clear acceptance criteria. Include
explicit requirements about what success looks like when prompting an agent.
Consider the difference between these two prompts:

```txt
Add error handling to the API
```

versus

```txt
Add error handling to the user authentication API endpoints. Ensure that:
- 401 errors return a JSON response with an error message
- Network errors are logged to the console
- The UI displays a user-friendly error message
- All error scenarios include appropriate HTTP status codes
```

The second prompt provides measurable criteria that both the AI agent _and_ the
reviewer can use to validate the implementation.

#### 4. Prioritize shell executable tooling

When building projects that will be worked on by AI agents, invest in tooling
that can be executed from the command line. Tools like ESLint, Prettier,
TypeScript, and test runners that expose CLI interfaces allow agents to validate
their work programmatically. This creates a tight feedback loop where the agent
can:

1. Make a change
2. Run validation tools
3. Adjust accordingly

Shell-executable tooling also enables CI/CD integration, ensuring that both
human and AI contributions are held to the same standard in quality.

#### 5. Implement robust static analysis

Static analysis tools catch issues before code can be tested. For projects
leveraging AI agents, this becomes even more critical. Tools like:

- **TypeScript** for type safety
- **ESLint** for code quality and pattern enforcement
- **Stylelint** for CSS/styling consistency
- **Prettier** for formatting

Prompt your agent to use these tools frequently:

```txt
Before completing a task, run static analysis scripts (`npm run lint`, `npm run format`, `npm run type-check`)
```

These tools act as guardrails, preventing common mistakes and enforcing
consistent patterns. When an AI agent makes a change that violates a linting
rule or introduces a type error, the tooling provides immediate, actionable
feedback.

> Static analysis tools catch issues before code can be tested

#### 6. Implement robust automated testing

Automated tests provide a safety net that's invaluable when working with AI
agents. A comprehensive test suite allows AI agents (and humans) to make changes
with confidence, knowing that regressions will be caught quickly. Tests should
cover:

- **Unit tests** for individual functions and modules
- **Integration tests** for feature workflows
- **End-to-end tests** for critical user paths

> A comprehensive test suite allows AI agents (and humans) to make changes with
> confidence

#### 7. Ensure static analysis and tests can be run locally, efficiently

Tooling that requires complex setup, long build times, or cloud resources
creates friction in the development process. For AI agents to iterate
effectively, static analysis and tests should:

- Run quickly
- Execute reliably
- Provide clear, actionable error messages
- Require minimal configuration or setup

Slow or unreliable tooling slows down the feedback loop.

#### 8. Prioritize test quality over coverage

While high test coverage might seem desirable, the _quality_ of tests matters
more than quantity. A few well-written tests that validate critical user
workflows provide more value than hundreds of shallow tests that check
implementation details.

Focus on tests that:

- Validate behavior from the user's perspective
- Cover critical business logic and edge cases
- Remain stable when implementation details change
- Fail clearly when something breaks

When prompting AI agents to write tests, explicitly request tests that validate
_behavior_ rather than implementation details. This ensures the resulting tests
remain valuable over time.

**Avoid** tests that purely increase code coverage metrics.

When in doubt, use the
[testing trophy](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications)
as a guide.

#### 9. Require PR/MR openers to prove their change works

Whether human or AI, the engineer opening a pull request (or merge request)
should demonstrate that their change works as intended. This might include:

- Screenshots or screen recordings for UI changes
- Test output showing passing tests
- Before/after examples
- Steps to reproduce and verify the fix

When prompting an AI agent to implement a change, explicitly request evidence
that the change worked. For example:

```txt
After implementing the dark mode toggle, provide a screenshot showing the
toggle in both light and dark states, along with the test output demonstrating
all tests pass.
```

#### 10. Review code thoroughly

AI-generated code should receive the same level of scrutiny as human-generated
code! In fact, AI code and human code should be indistinguishable. During code
review, look for:

- **Security vulnerabilities** (XSS, SQL injection, command injection)
- **Edge cases** that might not be handled
- **Performance implications** of the implementation
- **Maintainability concerns** like overly complex logic
- **Consistency** with existing codebase patterns

Don't assume AI-generated or human-authored code is correct. Thoughtful review
remains one of the most valuable quality controls in the software development
process, particularly in the agentic era.

## Conclusion

AI agents are powerful tools that can dramatically increase development
velocity, but their effectiveness depends on engineering best-practices. By
applying staff-level engineering techniques such as clear communication,
constrained scope, robust tooling, comprehensive testing, and thorough review,
teams can leverage AI agents to ship high-quality code at scale.


Using AI agents to effect product change - not just lines of code.

Staff-level engineering with AI agents

---
title: Avoid stateful components in design systems
description:
  Design systems should very rarely leverage internal state when building
  re-usable UI components
date: '2025-11-05'
image: 'dmytro-yarish-KgtOr1cCECw-unsplash.webp'
---

Design system components should be thought of as akin to Lego bricks &mdash;
composable pieces of a user interface that empower engineers working on
applications to build consistent and branded user experiences. At times, design
systems drift towards larger, stateful components to help with code sharing and
re-usability. In theory, this makes sense! In practice, however, design system
teams rarely have the business context required to successfully engineer
components that can handle a wide enough variety of use cases.

How can a design systems team identify when a component is veering into this
territory, and becoming less like a Lego brick and more like a glued-together
Lego kit? It all starts with **internal component state**.

## Stateless components

Design system components tend to expose customization options via component
props and event handlers. Consider a simple button component:

```tsx
function Button({
  variant,
  children,
  onClick,
}: {
  variant: 'primary' | 'secondary' | 'destructive'
  children: React.ReactNode
  onClick: (e: React.MouseEvent<HTMLButtonElement>) => void
}) {
  return <button onClick={onClick}>{children}</button>
}
```

The button accepts three props (`variant`, `children`, and `onClick`). The
button has _no opinions about what happens when it is clicked_ but allows
application engineers to handle those decisions in their application code.

## Stateful components

The `Button` we defined as part of our design system, **maintains no internal
state** and is updated entirely from the outside.

Next, our team wants to tackle a `SortButton` component that can be used in
sorting scenarios for other UI elements like data tables. According to the
provided UX specs, when clicked, the sorting state for the button should toggle
between `"none"`, `"ascending"` and `"descending"`.

```tsx
import { type ComponentProps, useState } from 'react'
import { Button } from '@com/ui'

function SortButton({ children, onClick, ...props }: ComponentProps<typeof Button>) {
  // `useState` here allows for reactive updates from inside the component as opposed to externally
  const [sort, setSort] = useState<'ascending' | 'descending' | 'none'>('none')

  /** Click handler to manage sorting state */
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    const getNextSort = () => {
      if (sort === "none") return "ascending"

      if (sort === "ascending") return "descending"

      if (sort === "descending") return "none"

      return "none"
    }

    setSort(getNextSort())

    /** Any passed-in onClick handler fires last */
    onClick(e)
  }

  return (
    <Button {...props} onClick={handleClick}>
      {children}

      {sort === "none" ? ↕️ : null}

      {sort === "ascending" ? ⬆️ : null}

      {sort === "descending" ? ⬇️ : null}
    </Button>
  )
}
```

Now our `SortButton` updates the UI based on the next possible sort state.

## ...Three weeks later

Our design system is a raging success, and application engineers are using our
stateless `Button` and stateful `SortButton` components. The `SortButton` works
great for sorting tables and other organized data UI. What could possibly go
wrong?

### URL state

For many sortable/filterable user interfaces, the ability to determine state
from the URL is a common pattern using
[query string parameters](https://developer.mozilla.org/en-US/docs/Web/API/URL/search).
Our application wants to update a `SortButton` instance according to a query
string in their application URL with three different possible states:

```txt
https://app.mycom.com
https://app.mycom.com?sort=ascending
https://app.mycom.com?sort=descending
```

Unfortunately, our current `SortButton` is completely unable to handle this
feature request! The design system team never considered that something _other
than a user click_ could cause the state of the button to update. Because the
state of our component is controlled by an internal `useState` hook, our options
for updating this component (particularly in a non-breaking fashion) are limited
or at the very least, highly complex.

### Making the best of a bad situation

We can "fix" this problem by allowing external state to initialize the
`SortButton` component state:

```tsx
import { type ComponentProps, useState } from 'react'
import { Button } from '@com/ui'

type SortDir = 'ascending' | 'descending' | 'none'

function SortButton({ children, onClick, sort = 'none', ...props }: ComponentProps<typeof Button> & { sort: SortDir }) {
  // `useState` here allows for reactive updates from inside the component as opposed to externally
  const [sortState, setSortState] = useState<SortDir>(sort)

  /** Click handler to manage sorting state */
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    /** Determine the next sort state according to the previous sort state */
    const getNextSort = () => {
      if (sortState === "none") return "ascending"

      if (sortState === "ascending") return "descending"

      if (sortState === "descending") return "none"

      return "none"
    }

    // Internal state handling
    setSortState(getNextSort())

    // Any passed-in onClick handler fires last
    onClick(e)
  }

  return (
    <Button {...props} onClick={handleClick}>
      {children}

      {sortState === "none" ? ↕️ : null}

      {sortState === "ascending" ? ⬆️ : null}

      {sortState === "descending" ? ⬇️ : null}
    </Button>
  )
}
```

Now, the component can at least initially be updated externally with the URL
state like so:

```tsx
const url = new URL(window.location.href) // "https://app.mycom.com?sort=ascending"
const sort = url.searchParams.get('sort') // "ascending"

function MyApp() {
  return <SortButton sort={sort}>Sort items</SortButton>
}
```

Note that this "fix" **only works when the sort value is set before the
component first renders**. If the URL changes after the component is already
mounted (for example, when navigating with client-side routing or when users
manually edit the URL), the component's internal state won't update to reflect
the latest URL.

## Stateless from the beginning

The `SortButton` component could have been implemented successfully, taking in
the URL search updating _as well as any other source of state in the future_ by
building **stateless** components instead of **stateful** components. In fact,
by limiting design system components to only expose props and event handlers,
application engineers can handle state management while the complexity of design
system source code drops tremendously.

```tsx
import { type ComponentProps } from 'react'
import { Button } from '@com/ui'

type SortDir = 'ascending' | 'descending' | 'none'

function SortButton({ children, sort = 'none', ...props }: ComponentProps<typeof Button> & { sort: SortDir }) {
  return (
    <Button {...props}>
      {children}

      {sort === "none" ? ↕️ : null}

      {sort === "ascending" ? ⬆️ : null}

      {sort === "descending" ? ⬇️ : null}
    </Button>
  )
}
```

The component definition itself is nearly half as long, and can account for any
future external state that an application engineer might use to handle sorting.

Then, an application engineer can control the state of the button, keeping it in
sync with any required business logic or source of UI state. In this example,
the `MyDataTable` reads from and updates the application URL in response to user
clicks of the `SortButton`:

```tsx
function MyDataTable() {
  const [searchParams, setSearchParams] = useSearchParams()
  const sort = (searchParams.get('sort') as SortDir) || 'none'

  const handleSortClick = () => {
    /** Determine the next sort state according to the previous sort state */
    const getNextSort = () => {
      if (sort === 'none') return 'ascending'

      if (sort === 'ascending') return 'descending'

      if (sort === 'descending') return 'none'

      return 'none'
    }

    setSearchParams({ sort: getNextSort() })
  }

  return (
    <SortButton sort={sort} onClick={handleSortClick}>
      Sort items
    </SortButton>
  )
}
```

## Conclusion

Design system components are Lego bricks from which to build larger user
interfaces &mdash; they should not ship glued together Lego kits with their own
internal state! In general, **avoid building a design system component that
manages its own internal state**. Keep components simple and stateless, by only
providing props and event handlers.


Design systems should very rarely leverage internal state when building re-usable UI components

Avoid stateful components in design systems

---
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

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

The latest

Staff-level engineering with AI agents

Avoid stateful components in design systems

Type safe, auto-generating test data for API mocking

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