Code coverage is a peculiar metric. It’s spawned a lot of debate and the views on it differ quite significantly in the JavaScript community. On its own, it’s a tool. Like any tool, it can be useful but it can also be misused. 

Let’s talk about code coverage and how you should (or shouldn’t) be using it when testing modern web applications.

## What is code coverage?

*Code coverage* is a metric that measures how much of the tested system is run during the test.

Imagine you have a simple `sum()` function that adds any two given numbers:

```jsx
// sum.js
export function sum(a: number, b: number): number {
	return a + b
}
```

And then a test case for this function covering its intention:

```jsx
// sum.test.js
import { sum } from './sum.js'

it('adds two given numbers', () => {
	expect(sum(2, 5)).toBe(7)
})
```

The code coverage of this test is 100% because the entirety of the `sum()` function has been executed during the test run (it quite literally has only one line of code). In other words, this test covers everything that the `sum()` function *does.*

Let’s take a look at another example.

The `getParity()` function accepts any number and returns either an `"odd"`  or an `"even"` string depending on whether the given number if odd or even, respectively.

```jsx
// get-parity.js
export function getParity(input: number): 'odd' | 'even' {
  return input % 2 === 0 ? 'even' : 'odd'
}
```

```jsx
// get-parity.test.ts
import { getParity } from './get-parity.js'

it('returns "even" given an even number', () => {
	expect(getParity(2)).toBe('even')
})
```

Despite the `getParity()`  function only having one line of code, it has *two logical branches*:

- The `"even"`  string is returned if the `input`  is even;
- The `"odd"`  string is returned if the `input`  is odd.

Since our test only covers the first logical branch, the code coverage for the `getParity()` function is 50% (we are missing tests for the `"odd"`  behavior).

### Code coverage criteria

There are a number of different criteria that determine code coverage. Most used criteria in practice are:

1. **Statement coverage**, measures if every statement of the program has been executed;
1. **Branch coverage**, measures if every branch of the behavior has been executed;
1. **Modified condition/decision coverage**, measures if every possible *input* and *output* of the program has been achieved.

You can often find these and additional code coverage criteria when using tools like [Istanbul](https://github.com/gotwarlost/istanbul):

```jsx
----------------|---------|----------|---------|---------|-------------------
File            | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------------|---------|----------|---------|---------|-------------------
All files       |     100 |       50 |     100 |     100 |                   
 get-parity.ts  |     100 |       50 |     100 |     100 | 2                 
----------------|---------|----------|---------|---------|-------------------
```

## Code coverage in practice

Taking its roots from the safety-critical systems, like avionics and spacecraft engineering, code coverage provides a ton of value in that context. Building and testing applications where the cost of a bug is measured in human lives doesn’t leave much room for debate. The software of that caliber has to be analyzed and verified to the last bit of information, to the farthermost logical branch in the code.

The practical application of code coverage for the rest of us varies. It’s essential to understand that *code coverage is a tool*. It can be useful and it can also be harmful. It’s not a panacea and it mustn’t drive your entire testing effort.

Code coverage can be a valuable instrument in detecting the logic you missed when testing, as well as identifying dead code and giving you more context on what exactly gets tested in your app. 

For library authors, code coverage is a great way to ensure all the public APIs their library is shipping is covered with tests. For those working on product development, code coverage can still be useful but has to be approached with a much higher degree of caution. In my practice, adopting code coverage in companies degrades the development and testing experience more often than it improves it. That is in no way a fault of the tool but rather of the hands wielding it.

At the end of the day, any tool is only as good as your understanding of it. That understanding, inevitably, involves knowing the shortcomings and caveats of the tool. Let’s talk about those.

## Caveats

### Implementation-driven

Code coverage is by design derived from the implementation of the system. It can be an easy way for the implementation detail testing to sneak its way into your test suite, harming its reliability and making you go after numbers instead of focusing your tests on what really matters—[the intention behind the system](https://www.epicweb.dev/the-true-purpose-of-testing).

The requirements toward modern software have grown rather complex. It’s not seldom you will find yourself writing multiple lines of code and performing a number of logical operations to achieve a *single intention*. 

And it’s crucial to put that intention first when testing your code. Following code coverage will never encourage you to do that. In fact, it will encourage the opposite. It’s a metric on machines by machines. But you aren’t writing tests for machines, you are writing them for yourself! Ultimately, *you* are the only one making calls in your testing strategy, and you are the judge of the test’s usefulness, whether you want that or not.

Because here’s the truth:

> *The only thing code coverage encourages you is **to write tests that run 100% of your code**.*
> 

This is an extremely slippery direction to follow. Not only will this waste your time but it will result in absolutely useless tests that bring no value (but do bring higher coverage!). 

> *Kent C. Dodds makes an interesting argument about the 100% code coverage in his [Common Testing Mistakes](https://kentcdodds.com/blog/common-testing-mistakes) article. I highly recommend you read it!*
> 

Good testing practices always derive from the intention-driven testing. By design, code coverage cannot give you any details or metrics related to that intention. It’s incapable of understanding it.

### Limitations

Code coverage is based on static code analysis. Machines are great at analyzing code but not that great at understanding the intention behind it. Our intention lives in the tests, not the code, so code coverage cannot predict what we are trying to achieve (neither should it, really).

> *Imagine writing software as writing a novel. Your intention is the message you put into the story. You then use words (the implementation, the code) to present that message to the reader. But the words alone aren’t the message. It may be hidden between the lines, only for the reader to uncover.*
> 

In practice, this simply means that code coverage isn’t always a reliable metric. It can produce both incomplete and straight incorrect results. Let’s look at the example.

Here’s a function called `isEven()` that accepts a number and returns a boolean indicating whether that number is an even number. In other words, given `1`  it will return `false` , and given `2`  it returns `true`, and so forth. That’s the intention, and here’s how we achieve it:

```jsx
// is-even.ts
export function isEven(input: number): boolean {
	return input % 2 === 0
}
```

```jsx
// is-even.test.ts
import { isEven } from './is-even.js'

it('returns true given an even number', () => {
	expect(isEven(2)).toBe(true)
})
```

Since the function has just 1 statement (`input % 2 === 0`), and that statement gets executed in the test, we will see 100% code coverage (try it yourself it you don’t believe me). But, wait, aren’t we missing something? What guarantees do we have that `isEven()` would return `false` given an odd number?

We don’t. But we do have a high number, the *highest* number, in fact. This is where code coverage can get misleading and rather dangerous. If the same metric can result both in testing the things you shouldn’t and forgetting to test what you should, one must treat it with extreme caution.

Which brings me to the next point.

### Misusage

It’s not unknown in business to base decisions around numbers. Code coverage is one of those numbers that I’ve seen managers and developers use to reason and asses various areas of product development. In fact, it’s an easy metric to get false assurance from, and I suspect that being a major factor why some teams feel tempted by it. If the percentage rises, then the team must be shipping good code, and if it falls, then the things aren’t going well.

Unfortunately, it’s not that simple. I understand the appeal of using a single metric—a magic number—to guide you through the dark forest which is automated testing. But ask yourself this: Where do I want to get?

Because if your goal is chasing higher numbers, then, by all means, you will get those. The problem is that testing isn’t about numbers. We write tests to help us ship more reliable software faster. We get there by *writing useful tests*. The lines of code executed during a test don’t define the test’s usefulness. Code coverage may be helpful but it mustn’t be a single thing that decides your testing direction.

Let me tell you a story. I worked in a team that relied heavily on code coverage. One day, I got a bug report that was causing customers trouble. I knew where the issue was, and after looking into it, I opened a pull request with a fix. Since this unexpected behavior managed to slip into production, I added an automated test for it to prevent regressions. With the changes pushed, I patiently awaited the code review.

While that was happening, an automated code coverage report came through. Turned out, my pull request decreased the code coverage of the product, which prevented me from merging it. “Nice!” I thought, since automations like this can be handy to spot mistakes. So I followed the report to find myself in the part of the product that neither have I changed nor that had anything to do with the bug. What’s even more surprising, the coverage drop was 0.0001%!

That failure did help! It helped us spot a misconfigured tool, which we then fixed. We owned the code end-to-end, that wasn’t a big deal.

But how many teams are out there who don’t own these automations? They can be set up by senior engineers, SREs, and CTOs who didn't give a proper thought into how blocking software delivery behind a code coverage threshold may backfire. How many developers are there who weren’t allowed to merge a legitimate bug fix, and were forced to chase contrived numbers?

I know there are far too many. That is why you shouldn’t follow any single metric blindly (and should also regularly review your automations to make sure they actually help you—that’s their only purpose).

> *Code coverage is a metric much like the line of code added and deleted in a pull request. Those numbers are useful, they give a higher picture. But you would never decline a meaningful change because it adds more LOC than it’s “supposed to”, would you?*
> 

And the opposite is true also. Code coverage reporting can be fooled and inflated, giving a high number without high returns. In my experience, I’ve seen it misused far more times than it ever provided actual value.

## When I would use code coverage

With all this in mind, when and how would I use code coverage today?

Truth be told, I wouldn’t. Unless I’m working on (human) safety-critical systems, I find the cost of introducing code coverage to significantly outweigh the gain.

> *I don’t want to become dependent on the coverage increase giving me a dopamine boost. I want to get that boost after writing mindful tests and getting the confidence from those tests, not the metrics.*
> 

I may use code coverage as a tool to help me audit the software I’m building and help find problematic areas in it on a run-and-see basis. I would then use that report and devise a testing strategy that makes sense in that particular case. I may revisit that analysis over time but I would not integrate code coverage automation into any of my projects, let alone allow it to drive my decisions when testing.

## Conclusion

Code coverage is a metric. It can be useful but its applications are niche enough to promote misusage, turning it into a harmful tool in the hands of those who chose to put too much trust in it.

On its own, code coverage must never drive your testing effort. If it happened to do so now, I highly encourage you to move away from it and spend the time you’d invest in pleasing the coverage percentage on learning what automated testing actually is and how to make the most out of it.

Dive into the contentious world of code coverage. Learn its nuances, pitfalls, and practical applications for modern web app testing

Making Use of Code Coverage

As humans, we are bound to chase understanding, and so we are also bound to seek structure and logic in things. Both give us a sense of order that, in turn, inspires and encourages us that everything can be learned, explained, and understood.

In my first year as a medical student, I had to memorize about 30 pages of human anatomy for every class only to be asked about a thing on page 31 the day after. Human anatomy has to be one of the most challenging things I’ve ever learned in my life (and I’ve learned JavaScript so that’s something). But it was crucial to understanding the human body. The bones, the muscles that attach to them, the ligaments to make them move, the nerves to control the movement, and the organs to help us function. All pieces fit in together because, in the end…

> ***The*** ***complex is inevitably built upon the simple.***

Testing your code is no different. It can be challenging and it can certainly be complex, and yet it always builds on top of much simpler basics.

Today, we will learn about the anatomy of a test, and for that, we will conduct an experiment!

## Dissecting tests

Putting our lab coats on 🧑‍⚕️, let’s examine different tests from various programming languages and see if we can spot something in common. To make things a bit easier on our eyes, we will write *the same unit test* in JavaScript, Go, Java, and Rust.

```jsx
// sum.test.js
it('adds two given numbers', () => {
  const result = sum(2, 5)
  expect(result).toBe(7)
})
```

```go
// sum_test.go
func Test_sum(t *testing.T) {
	t.Run("adds two given numbers", func() {
    var result = sum(2, 5)
		assert.Equal(t, 7, result)
	})
}
```

```java
// SumTest.java
public class SumTest {
	public void addsTwoGivenNumbers() {
    int result = sum(2, 5)
		assertEquals(result, 7);
  }
}
```

```rust
// sum_test.rs
mod tests {
	#[test]
	fn adds_two_given_numbers() {
		let result = sum(2, 5)
		assert_eq!(result, 7);
	}
}
```

Why, aren’t those quite alike!

First, naturally, we will have the actual *tested code* invoked one way or another (i.e `sum(2, 5)`). Then, there will always be an *assertion* that compares the actual and the expected result of the sum operation (i.e. `expect`, `assert.Equal`, `assert_eq`).

But looking even higher than that, each test has a *name*, and the *test function*, and a particular *arrangement* of classes, functions, or modules that make it a test. It’s almost as if there’s an ephemeral structure to them that repeats and stays true no matter the language… 

## Test structure

Any automated test, at any level, in any programming language consists of three main steps:

1. Setup.
1. Action.
1. Assertion.

Each step is important because each step has its own distinct purpose. We will look more closely at each of those steps below.

### Setup

The **setup** step is responsible for preparing everything around your tested code so the code would actually run. This makes it one of the most important steps of your test as it concerns itself with everything from the test environment and test definition to putting your code into a desired initial state, handling any unwanted side effects, and establishing the testing boundaries.

> I often like to explain the setup step as a “box”. You test your code by putting it in that box so you better make sure it has everything the code needs to work properly inside of it.


That being said, you don’t need the setup phase for every test you write.

In fact, if you are using a testing framework, it will do a lot of the setup for you. For example, you don’t need to prepare anything to call a simple `sum()` function in a test. Much of that is determined by the function itself since it’s pure, has no dependencies, and introduces no side effects.

Once you move to testing more complex code, the setup step becomes indispensable. It also becomes quite complex itself. I firmly believe that it is the setup step that must mitigate the most complexity carried into the test from your code (I talk about this in length in the “[Dissecting Complexity in Tests](https://www.youtube.com/watch?v=nUozijHdgMM)” talk so go watch it to learn what makes tests complex).

A few examples of the things you may see during the setup:

- Run you application or render an isolated component;
- Mock network requests;
- Use dependency injection;
- Initiate test databases;
- Wrap the tested code in providers.

### Action

The **action** step is about performing actions on the tested code.

```rust
sum(2, 5)
```

The actions you perform come from the expectations you have, and concern themselves with bringing your code to the expected state. In the case of the `sum()` function, the action is to call it with two numbers, and get the sum of them in return.

> In stateful systems, actions always make your system *transition* between states.


Not all the code you test will be as simple as `sum()`. Often, you would have to perform multiple different actions before making the assertion. It is important you don’t stray from the intended behavior you are testing and stay true to the [purpose of tests](https://www.epicweb.dev/the-true-purpose-of-testing).

Modeling your actions from the right perspective is equally as crucial. I believe Kent C. Dodds said it best:

> The more your tests resemble the way your software is used, the more confidence they can give you.


It’s important to remember that the test actions you write aren’t yours, they are *the user’s*. They belong to the person (or another machine!) who will be using your code with a particular intention in mind. So the more you model your actions to resemble those of the user, the better your test will be overall.

Here are some of the actions you may make in a test:

- Call functions and methods;
- Navigate to a particular page;
- Interact with DOM (e.g. click on things);
- Dispatch network requests.

## Assertion

The **assertion** step is where you compare the actual state of your system with the expected state.

```jsx
expect(actual).toBe(expected)
```

Once again, it’s quite straightforward with the `sum()` function: when given 2 and 5, you expect the result to be `7`. If it’s anything but 7, the test must throw because the intention behind the `sum()` function hasn’t been met.

> **Assertions are the most important part of any test.**


I honestly don’t know how to stress this enough. Assertions are the heart and soul of what the test is about because they are written around the expectations toward the code’s behavior (this is why you should generally have at least one assertion in a test).

Much like the actions, assertions also derive from the intention behind the tested code. But it may not always be clear what and to which extent to assert. When in doubt, remember the [Golden Rule of Assertions](https://www.epicweb.dev/the-golden-rule-of-assertions), and the fact that **assertions are only useful when they throw**, so you have to make them throw reliably and for a good reason.

Assertions can be literally anything, but here’s a few examples:

- The return data of a function is what you expect;
- A certain UI element is visible (or no longer visible) on the page;
- The browser has navigated to the next page.

## Conclusion

The three-step test structure is not something new. I’ve read about it a lot but I always found it strangely missing when talking about anything but unit testing. In practice, tests of any level follow the same structure since all tests need to prepare the environment and the system, perform some actions, and validate the result. Without much simplification, that is the essence of any test, and with a solid test structure, it makes it a tad easier to grasp

Explore the analogy between learning human anatomy and writing code tests, emphasizing a universal three-step structure: Setup, Action, and Assertion.

Anatomy of a Test

What if I told you there was a single rule that can reliably tell apart a good test from a bad one? 

This is not a trick, not a sales pitch. It’s a rule I’ve been using for years to help me refine my tests, make them less flaky and more valuable countless times. In fact, it’s such an indispensable rule in practice that I hereby coin it **The Golden Rule of Assertions**:

> A test must fail if, and only if, the intention behind the system is not met.

We talked about the intentions and the role they play in the [purpose of testing](https://www.epicweb.dev/the-true-purpose-of-testing) before. Now, it’s time to get some practical value out of adopting that mental model. 

## Assertions

The heart of every test lives in its *assertions*. Those are the expressions that compare the state of the system we expect and the state we get. Expressions like this one:

```jsx
expect(this).toEqual(that)
```

If that comparison fails, the assertion throws an error, letting us know that something is wrong. But it’s *when* the assertion throws that matters the most.

Let’s go through a few example of how The Golden Rule of Assertions can point out some critical mistakes you make in your tests.

## Implementation details

Consider the following code:

```jsx
import { cookieUtils } from './utils'

export function parseCookieName(cookie: string) {
  const { name } = cookieUtils.parse(cookie, { pick: ['name'] })
  return name
}
```

The intention behind the `parseCookieName` function is to accept a cookie string and return the name of the cookie present in it. To do it, it relies on some `cookieUtils` object for the actual parsing.

Now, a test for such a function may look something like this:

```jsx
import { parseCookieName } from './parseCookieName'
import { cookieUtils } from './utils'

it('returns the cookie name from the given cookie', () => {
  const cookieName = parseCookieName('sessionId=abc-123')

  expect(cookieUtils.parse).toHaveBeenCalledWith(
		'sessionId=abc-123',
		{ pick: ['name'] }
	)
  expect(cookieName).toBe('sessionId')
})
```

Since we only expect the cookie name, we are also asserting that the `cookieUtils.parse` has been called with the right `pick` argument. Seems reasonable enough.

But what will happen if the `parseCookieName` function doesn’t need `cookieUtils` anymore? Perhaps we adopt a well-established third-party package to do the parsing for us, or even implement a basic version of it ourselves.

Well, the test will fail:

```jsx
× returns the cookie name from the given cookie
  Error: expected the "cookieUtils.parse" to be called but it never was.
```

It’s good when tests fail. We write them so they do fail when something is wrong. But here’s the thing: *is* something wrong with the `parseCookieName` function? We don’t even know. The assertion that checks the returned cookie name isn’t even run because the `expect()` call that comes before it throws an error. 

The test fails while the intention behind `parseCookieName` isn’t necessarily broken. In fact, if we remove the `cookieUtils` assertion, the test passes! So the code was fulfilling the intention all along but the test still failed.

In this particular case, it happened because we introduced an assertion over the implementation detail—the usage of the `cookieUtils` object. It doesn’t really matter *how* we get the cookie name. As long as we do that, the function does what it was intended to do. 

This is why testing implementation details is discouraged. Because if those details change or get removed, your test will fail even if the code you are testing remains perfectly functional. The Golden Rule of Assertions helps you decide what to test and what to omit.

> The implementation may change but the intention stays the same.

## Test boundaries

Okay, we learned our lesson and don’t include implementation details in our tests anymore. Is this all this fancy new rule is about? Do we even need it now if that’s all it does?

I have another example for you:

```jsx
export async function fetchUser(id) {
  const response = await fetch(`https://example.com/user?id=${id}`)
  const user = await response.json()
  return user
}
```

The `fetchUser` function should fetch the user by `id`. How it does so—using the `fetch` function—doesn’t matter in the context of the test, and so we write it accordingly:

```jsx
import { fetchUser } from './fetchUser'

it('fetches the user by id', async () => {
  const user = await fetchUser('abc-123')
  expect(user).toEqual({ name: 'Cody' })
})
```

Now, if we replace `fetch` with React Query, for example, the test will still pass as long as the returned user has the right value. No implementation details involved, we should be fine (you see this isn’t the end of the article, you know we aren’t fine).

What will happen to this test if the server returns an error? Or if the connection to `https://example.com` times out?

You guessed it—the test will fail.

```jsx
× fetches the user by id
  TypeError: Failed to fetch
```

Although we don’t mention any implementation details in our test, it still implicitly relies on one external factor—a GET request to the `https://example.com/user` endpoint. Because of this, apart from validating the `fetchUser` function, the test now also concerns itself with the validity of the server. This blows the scope of this test from a simple function to the network connection, server runtime, response timings… There are way too many moving parts—parts we may not own or control—for this test to ever be reliable.

> Despite the `fetchUser` function depending on the network call, it cannot guarantee the validity of the server, neither is it responsible for it. All it cares about is to make the right request and handle the response to return the expected user object.

None of those factors determine the validity of the `fetchUser` function. And to correctly test that validity, we must take the HTTP interaction out of the testing equation. In this case, we can reach out for API mocking tools like [Mock Service Worker](https://mswjs.io/) to make that network request a fixed, predictable given in our test.

> Keep in mind that mocking is just a tool to establish boundaries. In the context of this integration test, we are taking the network out because we gain no value from it at this level. We’d still have to test the `fetchUser` function end-to-end where keeping that request un-mocked would be essential. Let me know if you would like me to cover mocking in more detail in future articles!

## Conclusion

I would like to stress that it’s not about mocking network calls or testing implementation details. Those are just symptoms of a larger problem when the test fails for any other reason than the broken intention. **When it doesn’t pass The Golden Rule of Assertions**.

In practice, this rule can encourage many best practices and help you spot problematic tests before they become such. It directs the spotlight on the importance of the testing setup and test scope, handling side effects and external dependencies, correctly written assertions and even incorrect implementations also.

So the next time you write a test, I want you to ask yourself: **When will this test fail?**

Luckily, you know exactly the rule to follow. The kind that will help you get the most out of your tests so they would shine like gold.

Learn about The Golden Rule of Assertions that helps pinpoint good tests from bad ones.

The Golden Rule of Assertions

Let me ask you a question: What are the automated tests for?

Whether you’ve written some tests in the past or not, you’ve likely heard that tests can be useful. And I know you’ve also heard stories about tests that are more of a chore and nuisance than any help. Frankly, I believe both parties are right! But to understand why, I will first let you in on a little secret.

**No test is inherently useful just because it exists. A test *becomes* useful when it fulfills its purpose.**

So, what is that purpose exactly?

As the name implies, automated tests are here to help us automate something. We take a particular state of our application, perform some actions, and check the resulting system to be what we expect. That’s what any test does, and yet some tests are more useful than others. There is precisely one thing that defines and controls that difference.

## The intention

Just as every piece of code exists for a reason, every test exists to verify the intention behind that code.

A paragraph is rendered when the user lands on a page, a request is made when they click a button, the right data is returned when a function is called—there is no count to the things we want computers to do. We then go and use a programming language the computer understands to *implement* that intention.

Sometimes, the intention and the implementation are the same. Take a look at this simple function that adds two numbers:

```jsx
function sum(a, b) {
  return a + b
}
```

The intention is for the `add` function to add any two given numbers `a` and `b`. Its implementation quite literally does just that: `a + b`. 

In the real world, however, our intentions are seldom as simple as that. We often write hundreds of lines of code to achieve one particular thing. We end up in the situation where the system’s implementation doesn’t directly correspond to the intention behind it. This is when the distinction between the intention and the implementation becomes crucial in the context of testing. 

## The purpose of tests

A test’s true purpose is tightly connected to the *intention* behind each test case, and can be put together as such:

> **You write tests to validate the intention behind the system.**

It is only when a test validates the intention that it becomes useful.

I’ve seen projects with hundreds, sometimes thousands of automated tests that contributed to nothing. They often broke across pull requests. They were hard to read and painful to navigate. They could’ve been removed tomorrow, and nobody would notice. With time, I came to realize what made them that way.

They had nothing to do with the intention of the code they were attempting to test. Instead of validating *what* the code did (the intention), they went in length to focus on *how* it did it (the implementation).

“[Don’t test implementation details](https://kentcdodds.com/blog/testing-implementation-details),” is a common advice you hear in automated testing. Hearing doesn’t mean understanding, and understanding doesn’t mean applying. We spend so much time writing code that we often become blind to the line between the intention and the implementation. In the end, we also intend every programmatic choice we make so why not test that?

You can only unlock the value of automated testing once you start treating implementation details as the means to an end, and focus on the larger intention at hand. Your users don’t know how the features of your app work, and neither should your tests. What the users do care about, is that whichever promises your app makes, whichever intentions it allows them to achieve, it does without fault.

Switching to this mental model also does wonders whenever you are unsure what to test. Suddenly, you can approach any system at any scale. When in doubt, test the intention. Always test the intention.

That’s what the automated tests are for.

Discover the true essence of automated testing and the difference between an implementation and intention.

The True Purpose of Testing

Chances are your app is lying to your users. I know you don't mean it. Building truthful apps is hard. But you've been lied to by so many other apps you use
and it is extremely frustrating. This frustration not only makes everyone's day worse, but it also makes users get out of that app as quickly as possible which for most apps is bad for the bottom line.

So what's the lie? Let me give you a few examples. Here’s what happens when you go to the [chase.com](https://chase.com) homepage:

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702738329/chase-lie.mp4" title="chase lie" />

Do you see the lie?

How about this one from a wikipedia article?

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702738329/wiki-lie.mp4" title="wiki lie" />

Here’s a humorous idea of what could have caused [the 2018 Hawaii false missile alert](https://en.wikipedia.org/wiki/2018_Hawaii_false_missile_alert) which is another good example of this lie:

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702738328/missile-test.mp4" title="missile test" />

It’s funny because we’ve all experienced it.

And no, it’s not just when the app loads either. We tell this kind of lie as the user uses the app. How about this one:

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702738328/chess-lie.hb.mp4" title="chess lie" />

I try tapping the "Rematch" and end up buying a Coke instead? Ugh! And this lie is also not just about things moving around either. Here’s another example of a lie:

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702738329/youtube-lie.mp4" title="youtube lie" />

So what’s the lie?

The lie is: **“We’re ready for you!”**

As demonstrated above, this lie can take many forms. Content layout shift is a big one, but also displaying things as if they’re interactive before they actually respond to user input is another.

And I would like to ask us all to please stop!

## How to stop lying

There’s no single treatment for this illness. The solution depends on the architecture of the app and the capabilities of that architecture as well as the constraints of the use case and product requirements.

The general principle is this: “If the app isn’t ready, don’t make it look like it is.”

It might be instructive to critique the examples above. Keep in mind that I don’t know the constraints and product requirements, so I’ll just share what would be optimal based on what I can tell from the outside.

For the **Chase Bank** homepage example, you might think they should just make a statically rendered HTML document and serve that on a CDN. However, I’m guessing they do some level of A/B testing and potentially client tracking (you’ve signed in before vs this is your first time here) so that won’t work. So the best approach for them would be to render the document on the server and use cookies for all the user-specific stuff.

**Wikipedia** could also benefit from the same approach. It’s very possible at their scale using a CDN for all that traffic could help a great deal in cost, and I’m guessing they want this bit to be dynamic to try different messages etc. Server rendering on the edge (most CDNs can do this) would definitely be the way to go here. But even without that there’s another way they could soften the blow: Make a nice loading state that’s properly sized according to the content that will appear there.

The problem is they don’t want to show the message to users who have dismissed it or already donated. I checked and they’re determining this based on a cookie called “centralnotice_hide_fundraising”. So you could easily solve this with a tiny bit of inline JavaScript in the `<head>`:

```html
<script>
if (document.cookie.includes('centralnotice_hide_fundraising')) {
    document.documentElement.classList.add('hide_fundraising')
}
</script>
```

And now you can use CSS to show/hide the fundraising section/loading state without making the content jump around.

For the fake **Hawaii Missile Warning System** thing. Just like, don’t do that at all. 😄 Just kidding, that’s actually very similar to the Wikipedia example and the [Chess.com](http://Chess.com) example. Similar solution to the problem. Just determine what you’re going to show the user earlier. If you really don’t know until some async stuff happens for one reason or another, then put in a loading state and then get your designer to come up with something good to put there in the event you don’t need to display the ad. They can come up with something better than a lie, I promise.

Finally, let’s talk about **YouTube**. Their example is super annoying. I experienced this myself as a user a couple years ago and it shocked me. And the reason it’s so especially frustrating is because they seem to go out of their way to make a worse experience. So, here’s what’s happening:

1. You go to YouTube
2. They send a blank HTML document (without the search `<input />` 🤡)
3. They start loading JavaScript (**lots** of it, like over 1.5MB!!)
4. The JavaScript loads which renders the search `<input />` but also clears the search box when you type and hit “search” 🤡
5. More JavaScript loads (**lots** of it, like another MB) which finishes the job and allows you to search

The reason this is annoying is because not only could they include the search `<input />` as a part of their initial HTML document, but they also could just *not disable the browser’s default behavior* and it would just work! In step 4 they are going out of their way to make it not work, then in step 5 they implement their own version of what the browser would have done much earlier on.

It’s clown town 🤡.

Again, I don’t know the constraints of their product requirements and architectural decisions. I’m just a user who thinks they can do better.

## Conclusion

There are many examples of both initial load lies and navigation lies. A Progressively Enhanced Single Page App ([PESPA](https://www.epicweb.dev/the-webs-next-transition)) architecture will elimintate almost all of these lies by default. But even then you need to be thoughtful about resources that load after your HTML document shows up (like images). [`aspect-ratio`](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) can help with that!

All of software development is trade-offs. Lying to your users about the readiness of your application is a great way to reduce trust in your brand. Stop lying to your users. You can do better. As you develop your software, ask yourself the question of whether your application ever enters a state where the user will think it’s ready for their interaction, but it’s really not and fix that. Build a truthful app.

P.S. One really cool thing about writing articles like this is it motivates you to fix the problems in your own stuff. So, years after the initial launch, I've finally fixed the really bad cumulative layout shift issues on kentcdodds.com using aspect-ratio 😂

<Video url="https://res.cloudinary.com/epic-web/video/upload/v1702923777/aspect-ratio.mp4" title="kentcdodds.com layout shift fix" />

Better late than never 😅

Stop Lying to Your Users

Have you ever wondered how many hours you sink into do the same thing in multiple projects? Re-making the same decisions, configuring the same tools, and wiring together the same libraries over and over again?

Back in the day it was things like Angular or React, Webpack or browserify, JavaScript or TypeScript, ESLint or ... not.

It’s even worse when you multiply these decisions by hundreds of engineers in a single org!

There was a ridiculous amount of repetition back in my time at PayPal. Not just in the code itself, but also repeated decisions to make.

It's incredibly inefficient to have each team making the same decisions again and again with every new project. And when those decisions differed project to project, collaboration across teams and projects became a big pain.

To top it off, just the process of making decisions reduces our effectiveness and overall happiness! (Read [Your App Makes Me Fat](https://businessofsoftware.org/2023/09/kathy-sierra-your-app-makes-me-fat/)).

So I did something about it.

I made an internal utility called `paypal-scripts` that was a wrapper around Webpack, TypeScript, Babel, ESLint, and a few other tools. It provided not only a project starter, but also a reference for how to use the tools and why they were chosen. Every time a new project was started, the developers had a **solid foundation** for building on. It was a **huge success**, and eventually the scripts became the standard way for new projects across the organization.

It’s been over 6 years since creating `paypal-scripts`, and people who are still working at PayPal tell me it's still maintained and used regularly. It's hard to quantify these things, but I have no doubt that by removing research and configuration time, this project has saved PayPal **tens of millions of dollars** in developer productivity so far.

This type of decision waste isn’t unique to PayPal. It’s prevalent across the entire web developer ecosystem.

It takes a lot to build web applications that deliver the great user experiences our users and bosses expect, and there are now more options than ever to choose from in every category of web development.

I saw a need for the same consistency and thoughtful opinions for the web development community at large, beyond the reach of developers at just one company.

That’s why the [Epic Stack](https://www.epicweb.dev/epic-stack) was created: to serve not only as a project starter for hitting the ground running, but as a useful reference for building fantastic web applications.

Here are some highlights of the tools included in the Epic Stack: Remix, React, TypeScript, Prisma, Zod, Conform, SQLite, LiteFS, Resend, [Fly.io](http://fly.io/), Radix, Shadcn, Tailwind, MSW, Vitest, Playwright, Testing Library, ESLint, and Prettier.

The Epic Stack also provides built-in support for everything you'd need in an application: testing, deployment, database migration, authentication (even 2FA and 3rd party auth), permissions, and more.

I highly encourage you to read the [guiding principles](https://github.com/epicweb-dev/epic-stack/blob/main/docs/guiding-principles.md) and [decision documents](https://github.com/epicweb-dev/epic-stack/blob/main/docs/decisions) behind every part of the Epic Stack. Additionally, there’s a huge list of [community-built examples](https://github.com/epicweb-dev/epic-stack/blob/main/docs/examples.md) that’s growing every day. You can also [watch a talk about the stack](https://www.epicweb.dev/talks/the-epic-stack) on the site.

You can think of [EpicWeb.dev](https://www.epicweb.dev/) as the primary documentation for the Epic Stack. In [the Volume 1 workshop series](https://www.epicweb.dev/products/full-stack-vol-1), we're iteratively building the Epic Stack so you'll understand all the pieces at a deep level.

Regardless of whether or not you use the Epic Stack for your projects, you stand to benefit from developing a deeper understanding for all of the moving pieces in an application– not just what they are, but **how to make choices** and **defend your decisions**.

Ultimately, what makes the Epic Stack great is the same as what made `paypal-scripts` great. 

It’s not the tools themselves, but the consistency and thought that went into their selection.

Developing the skill to understand and recognize this will take you far.

Streamline web choices, build top-notch apps efficiently.

How the Epic Stack Makes You Faster

From the perspective of web standards to concerns about increasing complexity, Kent C. Dodds shares his opinions on why he won't use Next.js.

Why I Won't Use Next.js

Where you store your application data has enormous impacts on your entire application. There are implications on the entire stack based on what you decide to use here.

There are terrific solutions like MySQL and Postgres that have become the default for many people. These are fine solutions. But for most web app use cases, you could drastically simplify your life by using SQLite.

SQLite is a sql-based database with a particularly unique feature: the entire database is in a single file. Largely for this reason, many people have historically seen it as a simple database for simple use cases.

However, in recent years SQLite has received a great deal of development and attention making it a simple database for even more advanced use cases. Let’s talk about some of those advancements and why for most of us, SQLite is the best balance of trade-offs.

## Zero Latency

The fact that SQLite is a single file on disk comes with a major benefit of 0 latency which [drastically reduces the "n+1 problem."](https://www.sqlite.org/np1queryprob.html) This means that as a developer you don’t have to spend so much time worrying about reducing the number of queries you’re making to the database (which can lead to less efficient queries and certainly less efficient developers).

And latency itself is not to be underestimated. If you’re not thoughtful about the distance between your database and your application, you can easily put a baseline on your application’s performance. It’s not uncommon for the app-to-database latency to be measured in the tens of milliseconds (and sometimes even hundreds). This means no matter what you do, your page can’t load with fresh data in less than that amount of time.

I know performance isn’t the number 1 priority of all apps, but it’s pretty important for most. I’m  pretty sure even though the business executive who paid for your app and doesn’t have alternatives doesn’t like loading spinners flashing in their face for every interaction. 🌀😠

## One Less Service

One huge benefit to SQLite is the fact that it runs as an embedded part of your application. So that’s one less service to babysit. Honestly, that was my primary motivation when I decided to migrate my own website from Postgres to SQLite. I just stick SQLite in the same volume I’m mounting for other data for my application already and I’m off the races.

This saves on complexity as well as cost.

And this is multiplied by the number of instances and replication considerations, but we’re getting ahead of ourselves… Let’s get into that…

## Multi-instance replication

As a file on disk, you cannot "distribute" SQLite directly. However, this is where there have been advancements in this space. For my own applications that need multiple instances, I use [LiteFS](https://fly.io/docs/litefs):

> LiteFS is a distributed file system that transparently replicates SQLite databases. You can run your application like it’s running against a local on-disk SQLite database but behind the scenes the database is replicated to all the nodes in your cluster. With LiteFS, you can run your database right next to your application on the edge. You can run LiteFS anywhere!
> 

On top of this, LiteFS has built-in support to handle the "Read Replica Consistency" challenge. So if you need your app to run in multiple instances, you need to use one of these tools.

Another solution here is [Turso](https://turso.tech/) which uses SQLite under the hood and even has a concept called "embedded replicas" for zero latency reads. Very cool!

## Database size

Another issue people sometimes bring up is database size. However, [SQLite is capable of handling databases that are an Exabyte in size](https://sqlite.org/hctree/doc/hctree/doc/hctree/index.html) (that's one million Terabytes, or one billion Gigabytes 🤯). Most of us web developers don’t work with near that amount of data. You’ll have much different problems before database size is one of them with SQLite.

Even putting large amounts of data in a SQLite database record is pretty efficient! In fact, in some cases, [it can be faster](https://www.sqlite.org/fasterthanfs.html) to retrieve data out of a SQLite database than from the file system 😆 SQLite is an incredible feat of engineering!

## Development and Testing

I know some of you reading this right now are perfectly comfortable running `docker compose` as a regular part of your workflow before you start developing your application. But you have to admit that it’s annoying to run multiple apps at once with conflicting databases and ports. With SQLite, it’s a total non-issue. It’s just a file. So you can run multiple instances of the same app at once with no trouble whatsoever.

Also, while starting up a new Postgres database is fairly involved (there are of course tools that make it easier), SQLite has no such issue. Again, it’s just a file. Run your production migrations/seed and you’re good to go.

And this ease carries over to the testing side of things as well. When your database setup is complicated, you end up spending time evaluating ways to mock out your database at the ORM level so you can avoid having to run and connect to your database during testing and the isolation issues that can happen as a result of that.

Not a problem with SQLite. It’s just a file! Each test can have its own database with barely a thought. Just a little bit of code to create and connect the database and then your tests can run on the full database. You can definitely do this with other databases, but not as easily and efficiently as SQLite.

## Weaknesses

SQLite is not without its shortcomings. And it would be unfair of me to just talk about where SQLite shines without addressing some of those.

- SQLite does not support subscriptions which can be a limitation on certain real-time use cases. However, there are plenty of reasons to recommend against using database subscriptions for real-time use cases anyway. Scaling real-time use cases is quite challenging, and personally have really enjoyed letting [Partykit](https://www.partykit.io/) do that part for me in my apps.
- SQLite being a file on disk does make connecting from external clients effectively impossible. But with [Fly.io](http://Fly.io) at least, it’s easy to run prisma studio on the production server and proxy that for local access. If you need to connect to it from another app, then you’re out of luck and have to set up HTTP endpoints on the host app for any data you need ([for now](https://github.com/superfly/litefs/issues/326)).
- SQLite does not support plugins like [TimescaleDB](https://github.com/timescale/timescaledb) for Postgres. While time-series data is possible with SQLite, I do not have experience with this use case and can't speak to the challenges there. My intuition says it's not advisable to use SQLite for that use case, but maybe someone else can offer me more insight.
- SQLite does not support enums which means you're forced to use strings. I have mixed feelings about this, but I mostly don't like enums anyway. The main drawback to this is when it comes to the typings for the client which doesn't allow you to ensure all values of a column are only within a set of specific possible values for the string. However, with Prisma client extensions, handling this kind of enforcement at the client (and typing) level [is possible](https://github.com/L-Steinmacher/epic-stack-with-prisma-client-extensions).

## Conclusion

So, can *you* use SQLite? For the vast majority of you reading this, the answer is “yes.” Should you use SQLite? I’d say that still for the majority of you reading this, the answer is also “yes.” Though it’s complicated. As with everything in technology, there are multiple solutions that will work out. But I think you should give SQLite a serious look due to the performance, simplification, and cost benefits I’ve mentioned.

And that’s why I’m using SQLite for my own applications and why I teach you to use SQLite in the [EpicWeb.dev](http://EpicWeb.dev) series of workshops.

– Kent

Why you should probably be using SQLite

Almost every web application requires authentication and authorization.

And while it is true that not every web developer needs to build the utilities that handle them, if you don’t *understand* what’s going on behind the scenes you’re doomed to make a potentially **disastrous** mistake.

Whether you've got a team at your company that handles auth, you're using a third party service, or you're building it yourself, understanding authentication and authorization are critical to your success at keeping your user's data secure.

When I was at PayPal, we had a team that was responsible for managing authentication (thank goodness). It was a major black box for me so when it came time to add end-to-end tests to our application that required authentication. Some people would just stick the auth flow in front of all their tests and call it good. But that’s not good. That’s the path to slower and more flaky tests.

Instead, I took the time to **learn about and understand** how our app’s authentication worked so I could simulate that authenticated state in our test environment. I used utilities built by the authentication team to help through the process as well.

It’s your responsibility to learn and understand the whole stack. Not because you’re going to be working on it, but because you’ll be more capable of collaborating with those who do. That’s what **staff-level engineers** are expected do.

This is why the [Authentication Strategies & Implementation](https://www.epicweb.dev/workshops/authentication-strategies-and-implementation) workshop on [EpicWeb.dev](https://www.epicweb.dev/) is so vital. It's a whole 21 exercises long covering a wide variety of tools and techniques that you need to understand to implement auth in your web application. Topics like cookies, sessions, passwords, permissions, verifications, and oauth are all there.

HTTP Cookies have been around since the very beginning of the web. They were invented to solve the problem of **state management** in web applications. Cookies allow websites to store small pieces of data on a user's device which is then sent along with every request to the server. This enables the server to maintain session information and remember user preferences across different interactions.

Cookies have become a fundamental part of web browsing and online user experiences, facilitating various functions such as session management, tracking user behavior, and personalization. However, due to privacy concerns, the use of cookies has evolved, and modern browsers provide users with more control over cookie settings, including options to block or delete cookies. Despite this, the most secure solution for managing user sessions is still to use cookies 🍪

Honestly, if your web-based application is using anything else for user authentication information, it's very possible you've got some security vulnerabilities. At OWASP's NZDay conference, Security Specialist Mike Haworth gave a talk titled "HTML5." Among the great security related information in [his slides](https://owasp.org/www-pdf-archive/OWASP_NZDay_2011_MikeHaworth_HTML5.pdf), you'll find:

> sessionStorage for session cookie?
> • Obviously sessionStorage is accessable by JS
> – Therefore session token theft by XSS is possible.
> – Cookie w/ HTTPonly flag set is not accessible by JS
> • Use Cookies with HTTPOnly for session tokens
> • Don't store sensitive info in browser storage

And this has not changed since his talk in 2011. Steer clear of using `localStorage` or `sessionStorage` for storing sensitive data like user sessions.

Understanding web authentication and authorization is an important part of web security (it's one of [OWASP's Top Ten](https://owasp.org/www-project-top-ten/) which "represents a broad consensus about the most critical security risks to web applications"). Having a clear understanding of web auth will help you avoid making simple mistakes in your implementation.

To gain even more perspective, you’ll definitely want to check out the [bonus interviews](https://www.epicweb.dev/bonuses/interviews-with-experts) with Auth0’s [Will Johnson](https://www.epicweb.dev/bonuses/interviews-with-experts/the-future-of-authentication-with-will-johnson), PlanetScale’s [Iheanyi Ekechukwu](https://www.epicweb.dev/bonuses/interviews-with-experts/scalable-databases-and-authentication-with-iheanyi-ekechukwu), and creator of the remix-auth library [Sergio Xalambrí](https://www.epicweb.dev/bonuses/interviews-with-experts/transitioning-from-rails-to-remix-with-sergio-xalambri). Each of these developers bring their own perspectives on the past, present, and future of authentication and authorization.

[Go get started](https://www.epicweb.dev)!

– Kent

Understand Authentication

Recently for the [Call Kent Podcast](https://kentcdodds.com/calls/04/20/what-is-full-stack-for-epic-web-dev), Brian left me a message asking what "full stack" means when it comes to Epic Web.

Here's my answer:

For the the Full Stack Vol. 1 release on Epic Web, "full stack" means that you will be building an entire web application in TypeScript. From adding stylesheets and scripting to the client side, to database optimization, implementing two-factor authentication, there's a ton of ground that gets covered.

Full stack application development requires a wide variety of tools, patterns, and techniques so the workshops use a lot of tools. Folks who went through the workshops report that even though they're not using all the same tools at work, they're still using the knowledge they gained from the workshops daily.

What you learn from the EpicWeb.dev workshop series is highly transferrable. By the end of the workshop series, you should feel confident to tackle problems in full stack web development, regardless of the tools you use.

That said, let’s get specific. In Epic Web, we’re basically constructing the [Epic Stack](https://github.com/epicweb-dev/epic-stack) from scratch. So we’ll be using TypeScript, React, Remix, Tailwind, Vitest, Playwright, Zod, Prisma, SQLite, Conform, Resend, Shadcn, Testing Library, and more. I’ve hand picked each of these tools (and even helped create some of them 😅) because they are the best in the business. It’s totally fine if you’re not using the same tools– Remember, people who have already done it are using what they learned with different tools.

One topic that is not discussed in depth in the first volume is DevOps. And that’s because [EpicWeb.dev](http://EpicWeb.dev) already has this covered for free! Check out [Deploy Web Applications All Over the World](https://www.epicweb.dev/tutorials/deploy-web-applications) tutorial on Epic Web will teach you how to deploy a multi-instance, multi-region app (with distributed data too!). It acts as a great companion piece to Full Stack Vol. 1.

Other DevOps-related topics like scheduling, error reporting, and monitoring will probably be part of the second volume (which is months away).

For now, think of "full stack" as being everything you need to know to build a secure, optimized application using TypeScript and other industry standard tools.

If you have any questions you'd like answered, leave me a message for the [Call Kent Podcast](https://kentcdodds.com/calls/04/20/what-is-full-stack-for-epic-web-dev)!

–Kent

What does “Full Stack” mean for Epic Web

Building web forms is one of the more challenging problems in web development (this is both hilarious and sad). I would say the biggest reason for this is because the web browser doesn't do enough for us.

What's interesting, is the browser actually does handle forms fairly well, but for most web applications we prevent this default behavior `event.preventDefault()` because it just doesn't do enough. This means we lose out on much of the work the browser _does_ do for us, putting us at even more of a disadvantage when working with forms in the browser.

Luckily, modern frameworks are starting to improve things in this area. Instead of us having to prevent the browser's default behavior and re-implement it all ourselves, frameworks like Remix emulate the browser's default behavior, but still allow us to enhance the behavior to satisfy our user experience requirements.

As a part of [EpicWeb.dev](https://www.epicweb.dev), I'm going to teach you how to utilize this powerful capability while addressing the needs of complex forms. Let's talk about it a bit.

## Web Form Challenges

Arrays, objects, and files are all challenging to represent in an HTML form. The browser doesn't have a clear mapping of arrays and objects to form fields (and vice-versa). The browser represents these fields using the [FormData](https://mdn.io/formdata) API which works ok, but isn't really something we work with directly very often. We need some kind of transformation layer to operate between us and the form APIs.

Another challenge with web forms is validation. Especially the bits that require the server to be involved like whether a username is taken in an onboarding flow. Just managing the state involved with that can be a pain (handling race conditions, etc).

Finally, we need to be able to handle the submission of the form. This is another area where the browser does a lot for us, but we often prevent that default behavior and re-implement it ourselves and often without considering re-submissions and other edge cases that the browser has predictable and consistent behavior around.

## Modern solutions

Remix helps a great deal with the submission of forms. It allows us to feel like we're using the browser's default behavior, but easily enhance the user's experience with things like optimistic UI, pending states, and error handling.

For example, here's some code from my talk [Bringing Back Progressive Enhancement](https://kentcdodds.com/talks/bringing-back-progressive-enhancement):

```tsx
function ListItem({ todo }: { todo: TodoItem }) {
	const updateFetcher = useFetcher()
	const toggleFetcher = useFetcher()
	const deleteFetcher = useFetcher()

	const complete = todo.complete

	return (
		<li className={complete ? 'completed' : ''}>
			<div className="view">
				<toggleFetcher.Form method="post">
					<input type="hidden" name="todoId" value={todo.id} />
					<input type="hidden" name="complete" value={(!complete).toString()} />
					<button
						type="submit"
						name="intent"
						value="toggleTodo"
						className="toggle"
						title={complete ? 'Mark as incomplete' : 'Mark as complete'}
					>
						{complete ? <CompleteIcon /> : <IncompleteIcon />}
					</button>
				</toggleFetcher.Form>
				<updateFetcher.Form method="post" className="update-form">
					<input type="hidden" name="intent" value="updateTodo" />
					<input type="hidden" name="todoId" value={todo.id} />
					<input
						name="title"
						className="edit-input"
						defaultValue={todo.title}
						onBlur={(e) => {
							if (todo.title !== e.currentTarget.value) {
								updateFetcher.submit(e.currentTarget.form)
							}
						}}
						aria-invalid={updateFetcher.data?.error ? true : undefined}
						aria-describedby={`todo-update-error-${todo.id}`}
					/>
					{updateFetcher.data?.error && updateFetcher.state !== 'submitting' ? (
						<div
							className="error todo-update-error"
							id={`todo-update-error-${todo.id}`}
						>
							{updateFetcher.data?.error}
						</div>
					) : null}
				</updateFetcher.Form>
				<deleteFetcher.Form method="post">
					<input type="hidden" name="todoId" value={todo.id} />
					<button
						className="destroy"
						title="Delete todo"
						type="submit"
						name="intent"
						value="deleteTodo"
					/>
				</deleteFetcher.Form>
			</div>
		</li>
	)
}
```

### Pending UI

Let's say we want to add some pending UI to the "completed" state here. This is all we'd need to do:

```tsx
const isToggling = Boolean(toggleFetcher.submission)
```

If the toggleFetcher is currently being submitted, then we know we're in a pending state and we can style the form however we like, or render a spinner based on that and we're golden.

### Optimistic UI

That's easy stuff though. What about optimistic UI? In case you're unfamiliar, optimistic UI is a pattern that allows you to solve the problem of a slow UI based on network latency. For example, if you're on 𝕏 and you like a post, you'll notice the heart icon updates instantly even if you're on a slow connection.

Doing that is easy enough. Your action will almost always be successful. However, occasionally it will not be successful. For example, what if the post was deleted? In this situation, you need to reliably roll-back. This is what makes optimistic UI so hard and likely the reason many apps don't implement it.

Well, Remix makes this trivial in most cases as well. Because Remix manages the form submission and we have access to it, we can optimistically display the next state quite easily:

```tsx
const isToggling = Boolean(toggleFetcher.submission)
const complete = isToggling
	? toggleFetcher.submission?.formData.get('complete') === 'true'
	: todo.complete
```

The `formData.get('complete')` will read the value the user's submitting from the form:

```tsx
<input type="hidden" name="complete" value={(!complete).toString()} />
```

And that's it! The UI can just reference `complete` to know how to render properly. And because Remix handles form resubmissions and race conditions in a predictable and consistent way (modeled after the browser), we can reliably use the submission's `formData` to know what the user's trying to do and display optimistic UI based on that!

Not all optimistic UI is quite that simple, but most of it is, and it's awesome.

And then if there's an error from the server, we can retrieve that from `toggleFetcher.data` and display the error to the user... Speaking of which...

## Error handling, type safety, and accessibility

I've been in this forms game for many years and writing a function to validate every form field is a huge pain. On top of that, to make things as accessible as possible you need to also handle native HTML attributes for validation, like `required`, `max`, `minlength`, etc. And then when there is an error, properly associating that error to the relevant form field (or the form as a whole) and moving the user's focus to the field at fault is like, a whole thing.

You wind up implementing the code twice for this important reason:

Server-side validation is required to keep yourself safe. Client-side validation is required to give the user a good experience.

This is a huge pain without the right tools.

### Zod

As I've been around the block, it's become incredibly obvious that having schema-based validation is where it's at. Back in the day when I was maintaining [angular-formly](https://github.com/formly-js/angular-formly), I built my own schema-based validation library called [api-check](https://www.npmjs.com/package/api-check) (before prop-types was extracted from React). People also put together conversion libraries that would convert a json-schema into the angular-formly field template so you could have persist-able form configuration and people built their own form CMS. It was pretty cool!

Bottom line: schema validation is powerful.

This is one reason I'm bullish on using [zod](https://zod.dev/) for forms. It makes it easy to represent business logic as a validation schema that can be largely shared between the client and the server. For the pieces that don't work on both sides (like: the username/password they submitted is valid), you can have a base schema (validate the username and password fields independently) which you further refine on the server.

Here's an example of the login from the Epic Stack:

```tsx
const UsernameSchema = z
	.string({ required_error: 'Username is required' })
	.min(3, { message: 'Username is too short' })
	.max(20, { message: 'Username is too long' })
	.regex(/^[a-zA-Z0-9_]+$/, {
		message: 'Username can only include letters, numbers, and underscores',
	})
	// users can type the username in any case, but we store it in lowercase
	.transform((value) => value.toLowerCase())

const PasswordSchema = z
	.string({ required_error: 'Password is required' })
	.min(6, { message: 'Password is too short' })
	.max(100, { message: 'Password is too long' })

const LoginFormSchema = z.object({
	username: UsernameSchema,
	password: PasswordSchema,
	redirectTo: z.string().optional(),
	remember: z.boolean().optional(),
})
```

All of that logic is shared between the client and the server. But of course the logic behind the username and password being correct has to happen only on the server. So in our server-side `action`, we can do that by adding a transform to the `LoginFormSchema`:

```tsx
LoginFormSchema.transform(async (data, ctx) => {
	const session = await login(data)
	if (!session) {
		ctx.addIssue({
			code: z.ZodIssueCode.custom,
			message: 'Invalid username or password',
		})
		return z.NEVER
	}

	return { ...data, session }
})
```

If no session is created, then we add an issue to the context and return a value which will never be valid. This will cause the form to be invalid and the user will see the error message we added to the context.

Zod is an incredibly powerful tool for building validation logic.

You can learn more about how to use a zod `transform` with a form in the tip ["Use Zod for All Form Validation"](https://www.epicweb.dev/tips/use-zod-for-all-form-validation).

### Conform

But zod was not built specifically for forms and is missing a number of really critical features to make it work nicely for forms. Zod was built with objects and arrays in mind (as it should be). But form data comes from `FormData` which requires a bit of a transformation layer.

Additionally, converting the zod schema into something I can use to create my form is challenging because keeping things in sync between the native HTML attributes (like `name` and validation attributes), properly associating zod's errors to their fields, and focusing the user where they're supposed to go in the event of an error is definitely outside the scope of a more general-purpose library like zod.

This is where [conform](https://conform.guide) comes in. Conform behaves as the transformation layer between our zod schema and the form so we can generate a typesafe form with proper validation and error handling (including focus management). And then Conform allows us to parse the submitted `FormData` into the data we can use for our application.

Conform works great with Zod and Remix, and also works with other frameworks (even vanilla JS) and schema validation libraries. Here's an example of our zod `LoginFormSchema` with Conform:

```tsx
import { Form, Link, useActionData, useSearchParams } from '@remix-run/react'
import { conform, useForm } from '@conform-to/react'
import { getFieldsetConstraint, parse } from '@conform-to/zod'

// ...

const actionData = useActionData<typeof action>()
const [searchParams] = useSearchParams()
const redirectTo = searchParams.get('redirectTo')

const [form, fields] = useForm({
	id: 'login-form',
	constraint: getFieldsetConstraint(LoginFormSchema),
	defaultValue: { redirectTo },
	lastSubmission: actionData?.submission,
	onValidate({ formData }) {
		return parse(formData, { schema: LoginFormSchema })
	},
	shouldRevalidate: 'onBlur',
})
```

From there, we can apply `form.props` to our `<form>` element, `conform.input(fields.username)` will give us the props appropriate to apply to our username input (for accessibility and HTML validation attributes derived from the schema), and errors can be found in `fields.username.errors`. In the Epic Stack, we have a `Field` component that gives us a consistent way to render fields, but here's an example of how you'd render the username field without that:

```tsx
<label htmlFor={fields.username.id}>Username</label>
<input {...conform.input(fields.username)} />
<ul id={fields.username.errorId}>
	{fields.username.errors.map((error) => (
		<li key={error.code}>{error.message}</li>
	))}
</ul>
```

Here's an example of what could be rendered (copied and slightly modified from [the live site](https://www.epicstack.dev/login)):

```html
<label for="login-form-username">Username</label>
<input
	id="login-form-username"
	name="username"
	form="login-form"
	required=""
	minlength="3"
	maxlength="20"
	pattern="^[a-zA-Z0-9_]+$"
	data-conform-touched="true"
	aria-invalid="true"
	aria-describedby="login-form-username-error"
/>
<ul id="login-form-username-error">
	<li>Username is required</li>
</ul>
```

Check out those attributes! They're all derived from the zod schema. So if we added a `.optional()` to our zod schema, the `required` attribute would be removed. Isn't that awesome? No need to duplicate the rules. Which leads into the next important point...

Thanks to Remix actions, we get progressive enhancement. The form will work before the JavaScript shows up because we validate everything in the `action`:

```tsx
const formData = await request.formData()
const submission = parse(formData, { schema: LoginFormSchema })

if (submission.intent !== 'submit') {
	return json({ status: 'idle', submission } as const)
}
if (!submission.value) {
	return json({ status: 'error', submission } as const, { status: 400 })
}

const { username, password, redirectTo, remember } = submission.value
```

But most of the time, the user's experience will be enhanced by the JavaScript which includes client-side validation of the form with error handling as shown above with the `onValidate` callback.

To top it off, all of this is typesafe. If we decided to change from `username` to `email`, then we would get type warnings everywhere. From creating the form itself, to the `submission.value` in the `action`.

And conform supports all kinds of complexities with forms. You need a set of fields that represent an object? [`useFieldset`](https://conform.guide/api/react#usefieldset). You need a dynamically sized array of fields? [`useFieldList`](https://conform.guide/api/react#usefieldlist). And Conform supports file uploads without breaking a sweat as well.

Dive in deep in [the 📝 Professional Web Forms workshop](https://forms.epicweb.dev/).

## Conclusion

We've got some fantastic tools for building typesafe, progressively enhanced, accessible forms for the web. Let me know what you think when you try these tools out!


Learn how to use modern tools that offer the best user and developer experience for web forms.

Accessible, Typesafe, Progressively Enhanced Modern Web Forms

Modern web development is fantastic. There are so many great tools available!

Modern web development is exhausting. There are so many great tools available!

Each of these sentiments is true. What’s great is that most of the time, it’s hard to make a choice that is wrong. Seriously. The trade-offs of most of the frameworks and tools you could use to build your application fit within the constraints of the vast majority of apps.

Despite this, engineers consistently struggle with **analysis paralysis**. Nobody likes the feeling of having to make a decision they’ll have to live with for the foreseeable future and find out it was the wrong one. Like a hungry person getting hungrier looking over menu that’s too long and full of great options, engineers find themselves guessing and second guessing our technology choices.

On top of that, getting team of engineers running the same direction with the chosen technology can be a big challenge. There are numerous considerations, existing skills, training for new skills, the hiring pool, personal preferences and experience, and more.

Oh, and then once you’ve finally selected a web framework, UI library, testing framework, hosting provider, etc. etc. you have to wire everything together before any meaningful work can get done.

And all of this is just a **big distraction** from what we’re really trying to accomplish here: **ship a quality product**.

## It’s time to just ship

I’ve been developing modern web applications big and small for nearly a decade. In that time, I’ve worked all over the stack. Significant technical decisions I’ve made are still in use at my previous companies (like PayPal). I’ve also made a number of technical decisions that didn’t pan out very well at all and I had to pay the price.

With the help of my team, I’ve shipped web applications to millions of users all over the world as well as smaller internal apps to a handful of stakeholders. I have a solid grip on what it takes to ship excellent user experiences and make choices that keep developer velocity (and morale) high.

That’s why I’ve decided to encode my experience on how to build excellent modern web applications into **an opinionated project starter** that allows teams to ship their ideas to production faster and on a more stable foundation. And it’s called “The Epic Stack”:

![](http://res.cloudinary.com/epic-web/image/upload/v1683707705/epic-stack-logos.svg)

The primary goal of the Epic Stack is to help your team get over analysis paralysis by giving you solid opinions for technologies to use to build your web application. The Epic Stack is really two things:

1. A project starter
2. A reference implementation

For those of you starting a new project, you can use the `create-remix` CLI custom stacks feature to bootstrap your app with `npx create-remix@latest --typescript --install --template epicweb-dev/epic-stack` and you’ll be set.

But most people don't startup their computer every day and start a new project. Most of us work on an existing app. For those folks, the Epic Stack can be a great reference for configuring tools and integrating with solid libraries and services. <a href="https://github.com/epicweb-dev/epic-stack/tree/main/docs/decisions" target="_blank" rel="noopener">The Epic Stack decision documents</a> can also serve as a good place to find good arguments for the decisions and trade-offs made.

## The Epic Stack

There’s far too much for us to talk about in a single blog post, so I’ll encourage you to dive into the <a href="https://github.com/epicweb-dev/epic-stack/tree/main/docs" target="_blank" rel="noopener">docs</a> for more and [star the repo](https://github.com/epicweb-dev/epic-stack), but let’s get a high-level view of what you get when you use or follow The Epic Stack.

We’ll start with <a href="https://github.com/epicweb-dev/epic-stack/blob/main/docs/guiding-principles.md" target="_blank" rel="noopener">the guiding principles of the stack</a>:

* **Limit Third Party Services:** If we can reasonably build, deploy, maintain it ourselves, do it. This saves on cost and reduces complexity.
* **Include Only Most Common Use Cases:** As a project generator, it is expected that some code will necessarily be deleted, but implementing support for every possible type of feature is literally impossible. _The starter app is not docs_, so to demonstrate a feature or give an example, put that in the docs instead of in the starter app.
* **Minimize Setup Friction:** Try to keep the amount of time it takes to get an app to production as small as possible. If a service is necessary, see if we can defer signup for that service until its services are actually required. Additionally, while the target audience for this stack is apps that need scale you have to pay for, we try to fit within the free tier of any services used during the exploration phase.
* **Optimize for Adaptability:** While we feel great about our opinions, ever-changing product requirements sometimes necessitate swapping trade-offs. So while we try to keep things simple, we want to ensure teams using the Epic Stack are able to adapt by switching between third party services to custom-built services and vice-versa.

With that context, here are a few things you get today:

* [Remix](https://remix.run/) is the Web Framework of choice
* [Fly app deployment](https://fly.io/) with [Docker](https://www.docker.com/)
* Multi-region, distributed, production-ready [SQLite Database](https://sqlite.org/) with [LiteFS](https://fly.io/docs/litefs/).
* Healthcheck endpoint for [Fly backups region fallbacks](https://fly.io/docs/reference/configuration/#services-http_checks)
* [Grafana](https://grafana.com/) Dashboards of the running app
* [GitHub Actions](https://github.com/features/actions) with testing and deploy on merge for both production and staging environments
* Email/Password Authentication with [cookie-based sessions](https://remix.run/utils/sessions#md-createcookiesessionstorage)
* Transaction email with [Mailgun](https://www.mailgun.com/) and forgot password/password reset support.
* Progressively Enhanced and fully type safe forms with [Conform](https://conform.guide)
* Database ORM with [Prisma](https://prisma.io/)
* Role-based User Permissions.
* Custom built image hosting
* Caching via [cachified](https://npm.im/cachified): Both in-memory and SQLite-based (with [better-sqlite3](https://github.com/WiseLibs/better-sqlite3))
* Styling with [Tailwind](https://tailwindcss.com/)
* An excellent, customizable component library with [Radix UI](https://www.radix-ui.com/)
* End-to-end testing with [Playwright](https://playwright.dev/)
* Local third party request mocking with [MSW](https://mswjs.io/)
* Unit testing with [Vitest](https://vitest.dev/) and [Testing Library](https://testing-library.com/) with pre-configured Test Database
* Code formatting with [Prettier](https://prettier.io/)
* Linting with [ESLint](https://eslint.org/)
* Static Types with [TypeScript](https://typescriptlang.org/)
* Runtime schema validation with [zod](https://zod.dev/)

And that’s what we have today, here are some things that will likely find their way into the Epic Stack in the future:

* Powerful, yet simple sitemap control
* Error monitoring with [Sentry](https://sentry.io/welcome/)
* Ecommerce support with [Stripe](https://stripe.com/)
* Ethical site analytics with [fathom](https://usefathom.com/)
* Internationalization
* Image optimization route and component
* Feature flags
* Light/Dark/System mode (without a flash of incorrect theme)
* Documentation on production data seeding process

## More than a list of features

A list of features is fine, but really what you’re getting out of this is a break from analysis paralysis. You get to ship faster on top a solid selection of technologies and tools.

Additionally, my goal is to make the Epic Stack second-to-none with regard to learning resources so your entire team can all get up-to-speed on your stack quickly. And having your entire team on the same page with regard to your stack is invaluable.

And that’s what <a href="http://EpicWeb.dev" target="_blank" rel="noopener">EpicWeb.dev</a> will be all about: How your team can take the Epic Stack foundation and build a quality application on top of it.

## Conclusion

After all the time I’ve spent building web applications and learning from engineers with more experience than myself, I feel extremely confident that the Epic Stack will help tons of engineering teams focus on their core offering, move fast, and build excellent user experiences. I hope you give it a shot. Please join the community by participating in <a href="https://github.com/epicweb-dev/epic-stack/discussions" target="_blank" rel="noopener">discussions on GitHub</a> and <a href="https://kcd.im/discord" target="_blank" rel="noopener">the Epic Stack channels Discord</a>.

See you around the web!

Introducing an opinionated project starter that enables web development teams to ship their ideas to production more efficiently.

The Epic Stack

There’s this pattern I’ve been using in my apps that has been really helpful to me and I’d like to share it with you all.

Full Stack Components

The main thing that makes end-to-end type safety difficult is simple: boundaries. The secret to fully typed web apps is typing the boundaries.

Fully Typed Web Apps

Web is made up of technologies that got started over 25 years ago. Now, we are transitioning to a new and improved architecture for building web applications.

Epic Web Dev Articles

Making Use of Code Coverage

Anatomy of a Test

The Golden Rule of Assertions

The True Purpose of Testing

Stop Lying to Your Users

How the Epic Stack Makes You Faster

Why I Won't Use Next.js

Why you should probably be using SQLite

What does “Full Stack” mean for Epic Web

Accessible, Typesafe, Progressively Enhanced Modern Web Forms

The Epic Stack

Full Stack Components

Fully Typed Web Apps

The Web’s Next Transition

Epic Web Conference 2024

Making Use of Code Coverage

Anatomy of a Test

The Golden Rule of Assertions

The True Purpose of Testing

Stop Lying to Your Users

How the Epic Stack Makes You Faster

Why I Won't Use Next.js

Why you should probably be using SQLite

What does “Full Stack” mean for Epic Web

Accessible, Typesafe, Progressively Enhanced Modern Web Forms

The Epic Stack

Full Stack Components

Fully Typed Web Apps

The Web’s Next Transition

Epic Web Conference 2024

Follow EpicWeb.dev