As a millennial, I started coding for the web early. I used to write static HTML pages and host them for free on an Apache server. But copy-pasting the same markup over and over was tedious... If only there were a better way! A tool you could use to generate pages from actual content, dynamically. Say hello to PHP and MySQL!

Shortly after, I wanted visitors to post comments and upload content too, so I rolled my own auth… storing passwords in clear text (of course). And since I hadn’t discovered the concept of sessions, I would transfer the same clear-text password and username back to each page via the URL so the users remained “signed in”. How fun?

Without knowing it, I had become a full-stack developer (not that the term existed yet… maybe a webmaster?). A bad one, but trying!

I love the process of facing a problem, working through it, and reaching the limits. Only then can one truly appreciate the effort others have put into solving the same problem, often in the most elegant ways.

There is something unique and exciting about the web

Back then, heavy desktop applications were still king. Executables could achieve much more than the web in terms of user experience. I dreamed of creating such programs, and it took me a long time to learn those skills…

But while building for the desktop was fun, something was missing. The truth is, there is something unique and exciting about the web that heavy desktop applications lack. With a website, you can connect with anyone in just a click, regardless of the hardware, operating system, or location. Updating content, rolling out new features, or fixing bugs happens instantly.

After graduating in 2007, I started working at a software company that sold both web and desktop applications. At that time, there was still a lot of space for the two to coexist. But eventually, JavaScript became good enough, and we converted most of our heavy clients to web applications. So I became a full-stack developer (again), writing SQL, implementing web services, configuring authentication, integrating with a framework, fetching data from the page, and rendering it.

We built the frontend using ASP.NET components, avoiding spaghetti jQuery as much as possible. We also became quite good at using the DOM and reducing network requests. However, managing and synchronizing state on complex pages was always a headache.

So, when React landed, it was love at first sight! React solved real-world problems. It had the same component approach we loved, and it removed a lot of complexity.

So I became the frontend guy, and I loved it!

I ultimately lost all interest in backend development. With the way the web was going, it became clear that companies needed specialized engineers who could master all those new libraries, avoid their pitfalls, and actively stay updated. So I became the frontend guy, and I loved it! The same can probably be said of backend developers who abandoned all frontend development and truly embraced serverless architecture and its infrastructure.

But the wind is changing again.

Not only the separation between the back and the front end has created silos and boundaries between the two worlds, it has become apparent that it also came at the expense of performance and simplicity.

As I’m writing this, the client often has to bend to deal with whatever the API endpoints offer — usually a poor compromise between how the server structures its data and how the client would like to consume it. This leaves both back and front-end developers frustrated.

As a result, we make too many requests, fetch too much data, and put extra load on the client and the server. We implement caching to reduce round-trips, which in turn causes new problems, such as cache invalidation. We implement optimistic updates to hide issues with latency and pray that nothing ever goes wrong.

To reconcile the back and the front ends

And so, developers have started looking for ways to reconcile the back and the front ends.

Modern frameworks such as React Router 7 or TanStack Start let server and client code sit next to each other, while taking care of the plumbing. They also make pre-loading, caching, invalidation, and optimistic updates easier.

React Server Components (RSC) take this one step further by running your components on the server (or the compiler) by default, with a simple way to opt out when your component needs interactivity or local state (“use client”).

And if this wasn’t enough, sync engines, such as Zero, now allow frontend developers to code as if everything were local by creating a replica of the DB on the client. The engine itself handles the synchronization with the server, removing most of the complexity introduced by the network boundary, which is truly amazing!

Shipping a full project on your own is not as easy as it seems

But if you’ve been focusing solely on writing frontend code and consuming APIs written by others lately, you’ll quickly realise that shipping a full project on your own is not as easy as it seems.

Yes, there are plenty of resources and solutions for hosting your app. You can go serverless, you can use an all-in-one hosting solution, or you can host it yourself on a VPS. But how do you actually choose one?

What about the database? Which one will you pick, and what’s the cost of running it? Plus, how do you back it up and secure it?

At some point, you will also want to have users… and authorizations… So, will you roll your own auth, find a library that works with your stack, or integrate with a 3rd party provider?

Those are just a few random questions you will have to answer and problems you will have to solve before you can ship anything (I spare you the CI/CD part).

If you’ve been working as a frontend engineer in a medium or large company, chances are you’ve delegated those tasks to others to focus on the part you were good at instead…

Technology should aim to blur the line between the back and the front end

But as technology shifts and development resources shrink (hello AI), there will be incentives for web development to simplify and ship faster. Multi-tier applications, micro-service architecture, strict separation between the client and the server, and other trends have all failed to achieve this. They may have solved a few developer problems, but not consumer ones.

Software development should be more about solving business problems than fixing issues that result from our technical decisions. Whether you use a full-stack framework, RSC, or a sync engine, back and front should work hand in hand. The technology should aim to blur the line between the two and reduce the network to an implementation detail.

When I heard about sync engines, I decided to try Zero. I had no trouble running it locally, and I really enjoyed the developer experience and the speed of the app. I saw the future in it. But when I wanted to host my project, I realized that I knew little about AWS (the preferred hosting solution), and even less about Postgres (the only supported database). I looked at other cloud providers (GCP), but was not able to go very far. I was also shocked at the cost of running a database!

I have fallen behind by letting others at my job handle the server code, persistence, hosting, and auth.

Unfortunately, I have fallen behind by letting others at my job handle the server code, persistence, hosting, and auth. I am no longer up-to-date, and I have to learn how to run a DB, host an app, and set up auth again… the 2025-way.

Fortunately for me, it is now possible to write a full-fledged app with mostly frontend code, and a few additional functions on the server (think manipulating data or checking authorizations). The rest is mainly about discovering and configuring the tools to support it.

So, being a full-stack developer no longer means spending:

• 40% on the frontend,
• 40% on the backend,
• 20% on the rest (DB, tooling, infra)

But more like:

• 60% on the frontend
• 10% on the backend (which happens to be JavaScript)
• 30% on the rest (DB, tooling, infra)

Frontend developers are going to need some new skills

I don’t think all specialized backend or frontend developers will become obsolete overnight, as the solutions mentioned here are still fairly new. The industry has a lot of inertia, and it’s still as hard as ever to find good developers, specialized or not.

Frontend-oriented frameworks definitely won’t fit all. Large applications will keep complex logic and heavy processes on the backend. But in any case, we should stop throwing RESTful(-ish) APIs to the frontend. Instead, the frontend code should run closer to the source: either on the server, using RSC or another framework, or stay on the client, provided the data is synced there. No matter what, frontend developers are going to need some new skills…

So looks like we’ve gone full circle and the world is calling for full-stack developers… again 🙌

If you’re still here, check this out and see which full-stack developer you want to be!

• TanStack Start & React Router 7
• Impossible Components & JSX Over The Wire on YouTube (RSC)
• Making React Fun Again with Sync

Why?

I like testing web apps. However, I came to the conclusion that the way we test them does not scale. So I recently embarked on a journey toward better frontend testing:

Are Playwright and Vitest ready to replace Jest?

After trying out a few things, I settled on the following strategy:

1. Write end-to-end (E2E) tests at route level to safeguard my acceptance criteria.
2. Write stories to test my components with different use cases.
3. Write regular unit tests for the rest (mostly utility functions).

You may have heard of the testing pyramid or the testing trophy before. These metaphors tell you where to invest your time and resources when testing. They give you an idea of the proportion of tests to aim for in each category (unit, integration, and end-to-end tests).

I have mixed feelings about that.

First, the boundary between each kind of test is blurry. People have different definitions for unit, integration, and E2E tests, especially in web applications.

Second, the testing pyramid is old. It was built on the assumption that E2E tests were slow, unreliable, and high-maintenance. This is no longer accurate. Tools have evolved and frontend developers can now build all kinds of tests directly into their apps. And thanks to the influence of Testing Library, these E2E and integration tests are also more resilient and easier to maintain than they used to be.

Third, these classifications don’t tell you how to get there. What shall you test? How? The proportion of tests, just like code coverage, is a consequence of your testing strategy. It’s not an end. You don’t test to reach a number.

Remember Goodhart’s law?

When a measure becomes a target, it ceases to be a good measure.

When a framework focuses on achieving a target percentage, it ultimately distracts people from their original objective, which is to have useful and meaningful tests.

So forget the testing pyramid and the trophy; let’s go for a burger instead 🍔!

Not a burger that will tell you how many E2E, integration, or unit tests to write —the result might look like a trophy, a square… or a blob. I don’t care. What I care about are the what and why. So, this burger will be a metaphor for an actual testing strategy instead.

But enough talking, let’s bite into it.

How do you test a burger?

1. Does it taste like a burger?

Take a big bite of your burger:

• Does it taste like a burger?
• Does it have the right consistency?
• Is it yummy?

Then you can confidently claim that you have a good burger.

But how does this translate to your app? Well, those big bites are end-to-end tests. They are vertical slices that cut through your entire app.

Use E2E tests to ensure your app meets acceptance criteria and performs as it should. In short, verify that your app delivers what you sold your customers.

For example, if your app is a TODO list, write E2E tests that verify that:

1. Users can add items
2. Users can complete items
3. Users can delete items

But that’s not enough, what about the ingredients?

2. Does it have the right ingredients?

If you pick each ingredient individually, do they live up to expectations?

• Is your salad the right size? Is it crunchy?
• Is your patty the right weight? Does it have the right amount of fat?
• How’s your tomato? Not too thin, not too thick?

This will tell you whether your ingredients meet the standards.

It also means you can change suppliers or improve the preparation, provided the ingredients still pass the tests.

And with those A-grade ingredients, you can make other quality burgers!

But what about your app? Testing ingredients is equivalent to testing components (= horizontal slices). Make sure your button performs as a button or your list renders the given items.

For example, your TODO app may have the following component tests:

1. The Card component renders a title, an optional description, and a checkbox
2. The checkbox toggles its state when clicked
3. The list renders the given items in the expected state

Components tests alongside E2E tests let you cross-test your app and ship with confidence.

But there’s one more thing…

3. Is your burger done right?

Last but not least, you might also want to check that you’re making burgers the right way:

• Are the ingredients stacked in the correct order?
• Is the sauce applied evenly?
• How do you bake your buns?

Any failure at the preparation level will most certainly affect the overall quality, aspect, or taste of the burger. So aren’t these tests redundant?

Probably, but they’ll help you identify issues faster than tasting the whole burger. Where did the salt get swapped with sugar? If you test your mayo recipe, you’ll know.

In your app, this means testing utility functions, processes, algorithms, and logic using regular unit tests. Provide inputs to the tested function and verify its output.

Your TODO app may not have many utility functions, but you could test the one that sorts items according to the creation date for instance.

This, folks, is the Testing Burger.

Vertical slices (E2E tests) + horizontal slices (component tests) + logic (unit tests) = Testing Burger 🍔

Before I wrap this up and ring the service bell️, I want to talk about the bun and why it matters.

So what about the bun?

The bun is the interface between your fingers and the burger. A bun has two halves, meaning two interfaces. Similarly, web apps have two interfaces: the underlying network and the browser.

I’m mentioning this because those two interfaces have historically been mocked in testing… with more or less success.

Not long ago, developers went to great lengths to mock the fetch API. But with the rise of tools such as Mock Service Worker (MSW), we can now use the actual bun. MSW simply simulates the paper around the burger, but the burger inside is real.

And what about the top bun or browser? In web apps, developers haven’t been able to use the browser for testing until very recently. It was either too slow, too unreliable, or it demanded too much infrastructure. So they used a fake bun instead: JSDOM. Sure it looked like a bun, but when you bit your burger, you could tell it wasn’t real: you had a hard time chewing and it tasted like Play-Doh.

However, developers are starting to use Playwright to test their apps in an actual browser. And Vitest browser mode, which is still in development, is making in-browser testing even easier. Tools such as Storybook also started embracing it to implement first-class component testing.

So we no longer have to fake the bun.

Your order is ready

Okay, E2E tests have already been around for a while (well, maybe not the ones that mock the network) and I’m sure you’ve tested components before too (even if called differently). So nothing is technically new here.

But before the rise of modern tooling, cross-testing your app would have been more painful and slower than it should be, and implementing the Testing Burger wouldn’t have made much sense.

I have huge respect for Martin Fowler and Kent C Dodds, who invented the test pyramid and the testing trophy respectively. If people started testing their apps, it’s mostly thanks to them. And if you listen to Kent, you’ll see that what he advocates resembles the Testing Burger. I just feel that these classifications are taking the problem from the wrong end and that the talk should be recentered on the actual testing strategy.

So if you’re a frontend developer, I hope the analogy speaks to you as much as it speaks to me. But if not, I hope it opened your appetite for testing 🤤

Hey! I’m Guillaume, a longtime frontend engineer. I want you to know that I will be writing a follow-up article with the actual, concrete, and step-by-step setup for implementing the Testing Burger. So if you’re looking forward to it, hit ‘Follow’ and stay tuned!

The Testing Burger 🍔 was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

What is wrong with frontend testing?

When you look at tutorials (including mine), everything is always nice and easy when it comes to testing an app, because:

1. it is a fresh install
2. it uses modern tooling
3. it has few dependencies
4. there are only a handful of tests

But when you try to test one of your existing projects, you have to deal with the following:

1. it was created with Webpack or Create-React-App (CRA)
2. the tools haven’t been updated in years
3. it has many dependencies, some of which are barely maintained
4. it already has some tests, with variable quality, questionable relevance, and an overall lack of strategy

I work on these projects—mostly enterprise software, with a fair share of technical debt. I have been using the tools available at the time and following the best practices highlighted in the Guiding Principles of Testing Library. And I have mostly enjoyed testing so far.

But I came to the conclusion that testing, in its current form, doesn’t scale. There is always a point where:

• tests are running slow and timeouts are becoming the norm
• it is common for code that works in the browser to fail in the test suite
• some portions of code rely so much on mocks that the tests lose relevance
• debugging without “seeing” is extremely painful
• some dependencies will break in the tests, with some obscure error (usually an issue with CJS vs ESM modules)

So what can we do about this? How can we enhance the developer experience (DX) and our tests at the same time?

Let’s explore a few options.

Jest

Jest is a testing framework developed by Facebook. It aims to provide a fast, simple, zero-config, and reliable way to test web applications. If the Jest API (test, expect, beforeEach, etc.) has stood the test of time (10+ years!), I’m not so sure it fully delivered on its promises… In 2024, Jest is neither fast nor easy to set up!

The other culprit, JSDOM, comes from the same era as Jest. JSDOM is a fake DOM implementation that you use to render components inside the test runner (= in Node, instead of the browser). Unfortunately, the implementation is partial and performance is poor by today’s standards.

Jest’s last major release was two years ago and the tool only has experimental support for ECMAScript Modules (the standard module system). JSDOM is barely maintained and the most downloaded versions (20.0.3 and 16.7.0) are over 2 years old.

And if you’re still using Jest through Create-React-App (CRA), I have bad news for you: you’re probably running versions of Jest and JSDOM that are over 3 years old 🙈.

Sure, you could always update Jest and JSDOM to the latest version and delay the inevitable… Even better, you could replace JSDOM with Happy DOM — another DOM implementation that is actively maintained and aims for better performance. The migration is pretty straightforward: replace one dependency (jsdom) with another (happy-dom), maybe fix a few edge cases, and off you go.

But based on my experience, you will only achieve marginal gains this way. The pain points I highlighted earlier will still exist.

Also, because of issues with third-party dependency, I’m willing to bet that you are currently using Jest’s ‘magic’ setting in your legacy projects: transformIgnorePatterns. The setting allows Jest to transpile problematic modules to a format it understands (CommonJS). While this mostly works, it is also terribly slow: the transformation happens before running the tests, which may take several seconds or even minutes.

OK, so what about Jest’s main competitor: Vitest?

Vitest

As the name suggests, Vitest is another testing framework that is part of the Vite ecosystem. Its API is very close to Jest, making it easy to migrate to Vitest without rewriting test cases. And just like Vite, Vitest can run straight from your sources (with minimal transformation), making it pretty fast to kick in.

Unlike Jest, Vitest uses ESM, the latest standard for JavaScript modules. While this works great with new projects, Vitest can be picky with your imports. Packages that are bundled improperly will cost you hours looking for solutions. You might have to use some workarounds that are either slow or inconvenient, such as inlining dependencies…

While Vitest is a step forward compared with Jest, you shouldn’t expect too much from it alone. Even if you manage to run it on a legacy project, you will probably not see a big performance boost. Testing times should improve (provided you didn’t inline too many dependencies…), but only marginally. And the developer experience will broadly be the same.

I’m afraid, testing web apps with a fake DOM simply doesn’t scale, no matter the tool. Mocking is a problem. Performance is a problem. Testing without seeing is also a problem.

So, what are the other options?

Playwright Component Tests

When Playwright announced component testing I started to get excited. The promise was to write tests just like with Jest and Testing Library, but have them run inside a real browser, instead of some fake DOM.

Problem solved? Well, not so fast.

Playwright component testing suffers from CSJ/ESM module hell, meaning you’ll have a hard time getting it running on a legacy project (unless the project has zero dependencies or all dependencies are perfectly bundled…).

And if you manage to get through this, you won’t be able to mock the network with Mock Service Worker (MSW) since it is not natively supported in component tests. You can still import MSW handlers via Playwright’s router as a workaround, but MSW won’t be available in your tests. This is such a letdown considering that MSW is one of the few tools developers are not looking to replace!

I hope the situation improves but for now, Playwright component tests are not an option.

Playwright (E2E)

So what about using Playwright directly, without component tests? I mean: use the Playwright API to open a page and write assertions against it.

My initial thought was: “Yuck! Playwright is for end-to-end testing (E2E). These tests sure have a place in the testing pyramid, but they should stay out of my app”.

Past the disgust, I decided to give it a try. But with one constraint: the tests should not hit an external system or service. They should be self-contained.

One of the advantages of using Playwright directly is that whatever runs in the browser runs in your tests. So unlike in component tests, we can use MSW to mock the network requests. This way, we can write predictable tests that don’t have any side effects, while working with the real app.

I found one caveat though: mocking authentication (eg OAuth) is hard, due to the nature and the complexity of the interactions involved. You can solve this by injecting a token in the page with Playwright (eg: by setting a global variable) and pass it to your auth library. This means creating a special setup (or configuration) for your app to run inside Playwright. There isn’t a magic recipe for this: use whatever works for you and your special requirements.

This was the tedious part.

The rest is pure joy! Once your app is set up, you can load routes, interact with the page, and write assertions. And the best part: you can see what’s happening in real time! The Playwright UI is a delight. It lets you access the console, view the network requests, and inspect the exact state of the page at any time, so it’s easy to debug when your assertions are failing. Oh boy, I was not ready for this!

So is Playwright THE solution?

Unfortunately no. It may be part of it, but it is not the ultimate solution. E2E tests are slow, even when mocking the network. Imagine refreshing the page after each test case! Sure, you could always bend the rules and load each page once, then run multiple test cases, with the risk of breaking isolation. I’m not sure I’m very comfortable with the idea yet.

Also testing solely at the route level is a no-go. I want to test components in isolation too, which is not possible with Playwright — the very issue component tests were supposed to address... If you want to test components individually, you first need to install a tool such as Storybook or Ladle, then write stories for them that you can use in the browser.

I did not like the thought of using another tool initially, so I tried writing a few custom routes by hand for each component, which I then tested inside Playwright. While the approach worked, I felt I was reinventing Storybook… without the DX.

So why not use Storybook instead?

Storybook Component Tests

Storybook is a tool used to build UI components. Whenever you write a new component, Storybook lets you add stories (= small snippets) in a file next to it, which you can then visualize in the browser. This allows developers to test their components through different use cases with instant feedback.

Although my overall experience with Storybook has been positive, some developers have expressed concerns that Storybook was bloated (too many dependencies). Luckily, the latest version (8.3 to date) addresses this, so this is no longer a fair thing to say. The tool has consistently improved and become faster since version 7.

It’s also been a while since Storybook understood that the future was with browser testing, not fake DOM. As it turns out, Storybook also comes with a test runner, which uses Playwright internally.

Component testing in Storybook consists of running your stories in a browser and verifying they render without errors, giving you some code coverage for free!

But stories alone can’t replace regular unit tests. So, Storybook lets you attach a play function to them, which you can use to write assertions and interact with the component. The API looks very familiar to Jest and Testing Library. This allows you to play and replay tests step by step within Storybook and run them in a test runner.

One source of truth (the story), many outputs! That’s what I call good DX.

That being said, running the test runner can be problematic in practice. The test runner requires Storybook to be up and running beforehand, which is not ideal in a CI pipeline or a pre-commit hook…

For this reason, I never regarded Storybook as a serious testing option... until the introduction of the new experimental Vitest plugin! This plugin substitutes the test runner with Vitest and uses browser mode to execute tests, doing all the heavy lifting for you.

Despite being in the early stages, it already works remarkably well!

But what is Vitest browser mode exactly?

Vitest browser mode

Vitest browser mode is similar to Playwright component tests. It has the same API as regular tests but renders in the browser thanks to an E2E provider — typically Playwright. Unlike Playwright component testing, it’s easy to get running and you can use MSW in your tests!

With Vitest Workspaces you can also run browser tests alongside regular unit tests. This makes it very convenient to collect code coverage from both sources. Because, yes, Vitest can collect coverage metrics in browser mode too — something that is hard to achieve with Playwright (see My Playwright code coverage journey). This might not seem like a big deal, but many companies require code coverage reports to be produced for all apps (often for the wrong reasons, but that’s another story).

So oddly enough, there is not much to say about Vitest browser mode: it’s simple, it’s fast, and it just works! Using browser mode does not require new knowledge. A bit of config is all it takes. Sure, it’s still experimental, but you can already see the potential.

My ideal setup… for 2025

Alright! This has been a long and tiring journey, but I have gathered enough information to identify where I want to head with testing now.

My ultimate objectives are:

1. to invest less time in testing
2. to get more coverage out of it
3. to have fast and reliable tests

So here is my strategy to achieve this:

1. write E2E tests at route levels with Playwright to safeguard my acceptance criteria
2. write stories in Storybook to test my components with different use cases, and run them using Vitest browser mode
3. write regular unit tests with Vitest for the rest (mostly utility functions)

This is what I call: the Testing Burger 🍔.

It’s worth noting that Vitest browser mode could be used to achieve point 1, but I prefer to use Playwright because it runs against the actual application, which gives me more confidence in the tests. Playwright’s GUI also offers a better developer experience than Vitest’s.

You could also use Vitest browser mode for component testing (point 2) but Storybook is well worth the extra overhead in my opinion. By leveraging the power of Storybook, you can develop components in isolation and test many use cases without breaking a sweat. Add a play function and some assertions to your stories and you no longer need regular unit tests.

For now…

The future I describe above is nearer than you might think. So if you like living on the edge, feel free to go for it now!

But here is what is missing for me:

• easy code coverage with Playwright
• Vitest browser mode is still experimental and docs are lacking—getting it to run requires trial and error (although when it works, it works very well)
• the Vitest plugin for Storybook is also experimental, and it will probably be for as long as Vitest browser mode remains so

That being said, you can start preparing for it now by upgrading your tools. If you’re in a Single Page Application (SPA), make sure to use modern tooling such as Vite or Rsbuild. Modern testing requires modern tooling. Depending on how old your project is and the amount of dependencies, this might take some time.

Then migrate your tests to Vitest. Again, you might encounter some issues with dependencies, but things are improving thanks to authors upgrading their libraries to ESM. This will not dramatically improve the speed of your tests (although you might see marginal gains when updating JSDOM or replacing it with Happy DOM). But since Vitest is a requirement for most tools I presented above, you will be ready to adopt them.

I would also start adding Storybook to projects with many components and ensure that stories are created when adding a new component. Even if the stories don’t run in your tests yet, the DX will start improving as a result.

Finally, I highly recommend getting familiar with Testing Library and its guiding principles. Modern testing tools were built with those principles in mind. Also, if you’re not using Mock Service Worker (MSW) yet, you probably should. No matter how and where you test, one constant is that you will have to mock the network. And there’s no better tool for this than MSW.

Hey! I’m Guillaume, a longtime frontend engineer. I want you to know that I will be writing a follow-up article with the actual, concrete, and step-by-step setup for my ideal testing setup. So if you’re looking forward to it, hit ‘Follow’ and stay tuned!

Are Playwright and Vitest ready to replace Jest? was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’re using Module Federation at work, you’re probably bundling your app with webpack. You might even have used Create-React-App (CRA) in some projects because you didn’t want to spend hours configuring them (I did 🤫).

You may have tried migrating to Vite despite the lack of official support for Module Federation. If so, I hope it went well (it can be challenging to convert a webpack project to Vite)…

Well, rejoice, because there is a new contender in the game: Rspack!

Rspack

Rspack aims to succeed at webpack (hopefully, at some point, webpack 6 will officially become Rspack). It’s written in Rust and it’s super fast. But for me, this is where Rspack really shines compared with the competition:

• Rspack supports most of webpack’s configuration, as well as existing plugins and loaders.
• Rspack has first-class official support for Module Federation

You can read more at:

Rspack

Rsbuild

Rspack is at the core of an ecosystem, where you’ll also find Rsbuild. Rsbuild is to Rspack what Create-React-App (CRA) is to webpack. Well, technically, Rsbuild is framework-agnostic. It supports React, Vue, Svelte, Solid, and more… So the equivalent of Create-React-App would be Rsbuild + its React plugin.

But just like Create-React-App, you can create a new project from scratch using the CLI (eg: npm create rsbuild@latest). And the upgrade path from CRA is pretty straightforward, thanks to their guide.

Also like CRA, Rsbuild is batteries-included. It is pre-configured to deliver a complete and performant React app, combined with great Developer Experience (DX). You don’t need to write any configuration to use it. Nonetheless, you may still override the default bundler configuration (Rspack) if you want to.

However, please note that, unlike Create-React-App, Rsbuild doesn’t include any testing tool. So you’ll have to manually add Jest to it to be on par with CRA (or better, consider upgrading to Vitest).

More info at:

Rsbuild

Module Federation

Now, the part you’ve all been waiting for: Module Federation! Both Rspack and Rsbuild support the brand new version of Module Federation (v2), which is no longer coupled to webpack (hello Vite!) and supports type sharing when running locally.

But, unless you’re starting a new project from scratch, you will want to stick with the first version of Module Federation (v1.5). Indeed, federated modules on v2 don’t work with modules on v1 (and vice versa).

This is perfectly fine with me! Since Module Federation v1.5 is compatible with v1, you can gradually update your Micro Frontend (MFE) applications to Rspack (or Rsbuild), and expect them to work seamlessly.

You’ll get full interoperability regardless of whether your applications use webpack, Rspack, Rsbuild, or a mix of them (I haven’t tried with a Vite application, but I expect you’d get the same results as when using it along with webpack, which I already had some success doing). Also, it doesn’t matter whether you update the host or the remote MFE first, Module Federation just works.

You can see some examples at:

• Rspack with Module Federation (v1.5)
• Rsbuild with Module Federation (v1.5)
• Rspack with Module Federation interoperability (Rspack with v1.5 + Rspack with v1 + webpack with v.1)

Currently, there are no examples available that show Rsbuild running along with other applications, but you can easily verify it works by modifying the last example (which I did).

Hot Module Refresh

Your experience with Hot Module Refresh (HMR) may vary. It’s always been a mixed bag for me when working with Module Federation, webpack, and/or Create-React-App. Sometimes it works, sometimes it doesn’t.

However, after upgrading the application to Rspack or Rsbuild, Hot Module Refresh started working, even when mixing it with older webpack MFEs 😅. I can’t promise it’ll work for you as I could not pinpoint what was causing the issue in the first place.

I’m glad Rspack and Rsbuild nailed that one because you can’t have good developer experience without HMR. So, no more hitting F5 to refresh the page and see your changes! Changes are instant!

Upgrade path

If you’re on webpack, it makes sense to migrate to Rspack. But if you’re on Create-React-App, you should rather migrate to Rsbuild.

If you’re upgrading to Rspack, you will need to update your Module Federation configuration. But fear not, it’s almost identical to the one you’re using with webpack. And the same goes for Rsbuild.

However, if you’re using a promise to resolve your remotes, beware that there is currently no official plugin to support it. You’ll have to do the dirty job by hand. See [Feature]: Module Federation supports runtime URLs.

Conclusion

I have been playing with Rspack and Rsbuild since the announcement of the alpha version, and my proofs of concept have been successful.

I have also been impressed by the support I received from the Rspack team; they were fast to answer questions and fix the issue I reported (HMR in Module Federation)!

Now that Rspack and Rsbuild are production-ready, I’m excited to start upgrading my projects and enjoy the new developer experience! What about you?

Cubed

Thank you for being a part of the community! Before you go:

• Be sure to clap and follow the writer ️👏️️
• Follow us: X | LinkedIn | YouTube | Discord | Newsletter
• Visit our platforms: CoFeed | Differ | In Plain English | Venture | Cubed

Module Federation users now have a clear upgrade path! was originally published in Cubed on Medium, where people are continuing the conversation by highlighting and responding to this story.

I remember the first time I tried to use my own Tab component with React Router. I thought it would be relatively easy to sync tabs with the current location. At worst, I should be able to find some examples online…

I was wrong.

Most tutorials show you how to match routes based on an absolute path, which works great… provided you know the full path and are willing to hardcode it. This was not an option for me.

I wanted my tabs to match paths within the parent route, no matter what path the parent route was using. If the path changed, or the tabs were to be nested under another route, the tabs should still work.

Scenario

We want to implement this app (the designer is on holiday and no one cares about the UI in the company 🙈):

The app consists of a single page with 3 tabs. Whenever the tab number changes in the URL, the corresponding tab should be selected, and its content should be shown.

When we click a tab, the URL updates accordingly.

Right now, the page displays at /sub. But this is likely to change in the future, so the tabs should work whether the page is rendered here or at /any/other/path.

We get extra brownie points for implementing accessible tabs.

Solution 1: <NavLink>

The easiest solution is to use the <NavLink> component from React Router:

import { NavLink } from "react-router-dom";

// ...

<NavLink to="1">Tab 1</NavLink>
<NavLink to="2">Tab 2</NavLink>
<NavLink to="3">Tab 3</NavLink>

<NavLink> automatically applies the active class name when the path in the to prop matches the current location. This works for both absolute and relative paths (relative paths resolve relative to the parent route).

It also has a few options to customize the active class name, the style, or children, and to tweak the default behavior. See the docs for details and the official tutorial for a complete example.

The interactive sandbox below uses the <NavLink> component to implement the scenario:

All is well, but things are never that easy (or are they?):

• <NavLink> renders a hyperlink (<a> tag); maybe you don’t want that?
• <NavLink> uses the aria-current attribute for accessibility; maybe you’d rather use the aria-selected attribute along with the tab role?
• maybe you want to use another library to render your tabs?
• maybe you have your own reasons?

Enough maybes, let’s explore other solutions now.

Solution 2: Router-aware Tabs

OK, so we’ll start with custom Tabs. Since we’re good people (and we like brownies), we’ll also try to make them accessible.

Let’s implement a component that plugs directly into the router, just like <NavLink>. We can use the following code (inspired by <NavLink>’s source code):

import { ReactNode } from "react";
import {
  useLocation,
  useNavigate,
  useResolvedPath,
  To,
} from "react-router-dom";

interface RouterTabProps {
  children: ReactNode;
  to: To;
}

function RouterTab({ children, to }: RouterTabProps) {
  const navigate = useNavigate();

  const { pathname: toPathname } = useResolvedPath(to);
  const { pathname: locationPathname } = useLocation();

  const selected = locationPathname.startsWith(toPathname);

  return (
    <button role="tab" onClick={() => navigate(to)} aria-selected={selected}>
      {children}
    </button>
  );
}

We have a <RouterTab> component that receives a path via the to prop (same as <NavLink>). This path can be either relative or absolute.

The path is resolved (useResolvedPath(to)) and matched against the current location (locationPathname.startsWith(toPathname)). If it matches, we set the aria-selected attribute to true, which provides basic accessibility and allows for styling.

Note that for the sake of this exercise, the component is implemented as a <button> with the tab role, which navigates when clicked.

We can now replace the <NavLink> components in solution 1 with <RouterTab>s:

<div role="tablist">
  <RouterTab to="1">Tab 1</RouterTab>
  <RouterTab to="2">Tab 2</RouterTab>
  <RouterTab to="3">Tab 3</RouterTab>
</div>

The full example is available in this sandbox:

Although this approach works, we should consider using tabs that aren’t tightly coupled with the router. This way, our tabs can be reused anywhere independently from React Router.

Let’s explore another solution.

Solution 3: Generic Tabs

A generic tab component that implements basic accessibility might look like this:

import { ReactNode } from "react";

interface TabListProps {
  children: ReactNode;
}

interface TabProps {
  children: ReactNode;
  selected?: boolean;
  onClick?: () => void;
}

function TabList({ children }: TabListProps) {
  return <div role="tablist">{children}</div>;
}

function Tab({ children, selected, onClick }: TabProps) {
  return (
    <button role="tab" onClick={onClick} aria-selected={selected}>
      {children}
    </button>
  );
}

Here we have a dumb <TabList> container and the actual <Tab> (a button with selected and onClick props). Your implementation might be smarter, but it doesn’t matter. The point is that the tabs don’t know anything about React Router or the current location.

To determine which tab is selected, you usually see solutions such as:

import { useLocation, useNavigate } from "react-router-dom";

// ...

const navigate = useNavigate();
const { pathname } = useLocation();

// ...

<TabList>
  <Tab onClick={() => navigate("1")} selected={pathname === "/sub/1"}>
    Tab 1
  </Tab>
  <Tab onClick={() => navigate("2")} selected={pathname === "/sub/2"}>
    Tab 2
  </Tab>
  <Tab onClick={() => navigate("3")} selected={pathname === "/sub/3"}>
    Tab 3
  </Tab>
</TabList>

This works well… provided you’re fine hardcoding the full path in the component ("/sub/1"). We’re not. See how we call navigate("1") to switch to Tab 1? We want the same for selecting it. So we should use a relative path instead. Something like this:

- <Tab onClick={() => navigate("1")} selected={pathname === "/sub/1"}>
+ <Tab onClick={() => navigate("1")} selected={pathname === "1"}>

OK, so how do you determine that a relative path matches the current location when your component doesn’t even know under which route it is rendered?

Here is one solution:

import { useMatch, useNavigate, useResolvedPath } from "react-router-dom";

// ...

const navigate = useNavigate();

const { pathname } = useResolvedPath("");
const route = useMatch(`${pathname}/:path/*`);
const matchedPath = route?.params.path;

// ...

<Tab onClick={() => navigate("1")} selected={matchedPath === "1"}>

Let me explain:

1. const { pathname } = useResolvedPath("") gives you the resolved path for the current route. Why? Because useResolvedPath resolves "" relative to the parent route. So this gives you the full path of the route where the component is rendered ("." would work too).
2. const route = useMatch(`${pathname}/:path/*`) will match anything under the current route (which we resolved to pathname). :path is used to extract the first segment of the path under that route. In other words, the relative path we’re after.
3. const matchedPath = route?.params.path extracts the :path value that we’ve just matched.

This feels harder than it needs to be. It’s not very elegant either, but this is the best I could find (this code has been working effectively for some time now). If you can think of a better way, please reach out 🙏

Let’s update our tabs with the code:

import { useMatch, useNavigate, useResolvedPath } from "react-router-dom";

// ...

const navigate = useNavigate();

const { pathname } = useResolvedPath("");
const route = useMatch(`${pathname}/:path/*`);
const matchedPath = route?.params.path;

// ...

<TabList>
  <Tab onClick={() => navigate("1")} selected={matchedPath === "1"}>
    Tab 1
  </Tab>
  <Tab onClick={() => navigate("2")} selected={matchedPath === "2"}>
    Tab 2
  </Tab>
  <Tab onClick={() => navigate("3")} selected={matchedPath === "3"}>
    Tab 3
  </Tab>
</TabList>

Now you have a generic Tab component that you can use with relative paths. See the full implementation for yourself:

Custom components are effective for addressing specific problems. They are also a good way to learn. However, it’s not advisable to reinvent the wheel... The custom tabs we’ve developed do not cover every scenario or edge case, and they are not fully accessible either.

For these reasons, let’s explore one last solution based on a third-party library.

Solution 4: Third-Party Tabs (React Aria)

Because we love good components and we want all the brownies 🤤, let’s use React Aria this time (React Aria comes with great accessibility).

The Tabs example on their website shows how to integrate with React Router. Unfortunately, the tutorial relies on absolute paths, which we don’t want.

So let’s mix our custom solution with React Aria tabs:

import { 
  useHref, 
  useMatch,
  useNavigate,
  useResolvedPath,
} from "react-router-dom";

import {
  RouterProvider,
  Tabs,
  TabList,
  Tab,
} from "react-aria-components";

// ...

const { pathname } = useResolvedPath("");
const route = useMatch(`${pathname}/:path/*`);
const matchedPath = route?.params.path;

// ...

<RouterProvider navigate={useNavigate()} useHref={useHref}>
  <Tabs selectedKey={matchedPath}>
    <TabList aria-label="Tabs">
      <Tab id="1" href="1">
        Tab 1
      </Tab>
      <Tab id="2" href="2">
        Tab 2
      </Tab>
      <Tab id="3" href="3">
        Tab 3
      </Tab>
    </TabList>
  </Tabs>
</RouterProvider>

The part that matches the path is unchanged. However, there are a few things worth explaining:

1. <RouterProvider navigate={useNavigate()} useHref={useHref}> allows for client-side routing. useNavigate and useHref are used to generate links that work with React Router. This is explained in their docs.
2. <Tabs selectedKey={matchedPath}> creates a container for the tabs, with the ID of the selected tab (matchedPath)
3. <TabList aria-label="Tabs"> creates the actual container with the tablist role and an accessible label
4. <Tab id="1" href="1"> is the actual tab element (tab role). href is the relative path for the tab, and id matches that path, so that the tab gets selected when selectedKey is the same.

When a tab matches, React Aria applies the aria-selected="true" attribute.

For the full example, see:

Conclusion

Syncing tabs with React Router is definitely achievable… once you know how to do it!

I would advise you to stick to <NavLink> as much as possible, or even use absolute paths if it’s not an issue. But if you need to use relative paths and <NavLink> isn’t an option, now you know what to do...

The techniques applied here will work with any component library. Moreover, their use is not limited to tabs alone. They can be used to create breadcrumbs, navigation menus, or any element that needs to synchronize with the current location.

Stackademic 🎓

Thank you for reading until the end. Before you go:

• Please consider clapping and following the writer! 👏
• Follow us X | LinkedIn | YouTube | Discord
• Visit our other platforms: In Plain English | CoFeed | Differ
• More content at Stackademic.com

How to implement Tabs that sync with React Router was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

The React Query way

As you may know, React Query returns the same instance (or parts of it) when the JSON in the server response remains the same between fetches (or partly the same).

React Query does this by deeply comparing the data and reusing instances for the parts that don’t change. This feature is called structural sharing:

React Query Render Optimizations

Structural sharing is important because React uses referential identity to decide whether to recompute memos, run effects, or rerender memoized components. If React Query returned new instances each time it fetched (or worse, each time the hook was called), apps would unnecessarily rerender (or worse, get caught in infinite rendering loops).

The broken way

If you’ve written a React hook before, there is a chance that you’ve also attempted to memoize its return value, so that it stays the same between renders (unless the value is truly different).

The usual way to achieve this is to useMemo. But this can get hairy when the memo depends on one of the inputs since you have little control over them.

For example, imagine you have a hook that takes an array in parameters and returns a computed array as output. The implementation might look like this:

export function useSomething(array) {
  const computed = useMemo(() => {
    return heavyDuty(array);
  }, [array]);
  return computed;
}

The output isn’t recomputed unless array changes. But, this only works if the caller is cautious about memoizing the array, which might or might not be the case…

For example, the hook could be called like this:

const filteredArray = array.filter(item => item.prop === someVar);

const something = useSomething(filteredArray);

Since filteredArray is a new instance each time React renders, the memo in the hook won’t have any effect!

So if your hook is:

• generic enough,
• performance-critical,
• or used in many places

You can’t just assume the caller will memoize all the necessary inputs beforehand.

Also maybe you don't want to punish the caller for not knowing all about your implementation details… Imagine if React Query forced you to memoize all your keys and inputs! I bet the user adoption wouldn’t be as high as it is now…

Stabilizing values with React Query

React Query uses the replaceEqualDeep function to achieve stability, or structural sharing (see source code and unit tests).

As things turn out, we can reuse the same function in our code to implement a hook that ensures a value remains stable between renders.

Introducing… useStable!

import { useEffect, useRef } from "react";
import { replaceEqualDeep } from "@tanstack/react-query";

export function useStable<T>(value: T) {
  const ref = useRef(value);
  const stable = replaceEqualDeep(ref.current, value);
  useEffect(() => {
    ref.current = stable;
  }, [stable]);
  return stable;
}

What the code does:

1. Export a function called useStable that takes a value as input
2. Use a ref to store the stable value (initially set to value)
3. Pass the current value and the previous one (stored in the ref) to replaceEqualDeep, which returns a stable value.
4. Update the ref with the stablevalue whenever it changes
5. Return the stable value

Step 3 is where the magic happens. React Query’s replaceEqualDeep function returns an instance that preserves identity at all levels. This means that:

• if the object or array is the same, it returns the same object or array
• but also, if not strictly the same, parts that remain the same (object properties or items in an array) still point to the same instances

Stabilizing the inputs

Now that we have a way to stabilize a value, let’s update our hook and stop worrying about ever-changing inputs:

export function useSomething(array) {
  const stableArray = useStable(array);
  const computed = useMemo(() => {
    return heavyDuty(stableArray);
  }, [stableArray]);
  return computed;
}

Thanks to useStable, the memo will work even if the array is a new instance at each render, provided the items inside the array remain the same.

Stabilizing the output

In the previous example, we stabilized the inputs. We did it because the computation was costly, and we wanted to do it as few times as possible. But in most cases, computing a value is cheap.

So instead of stabilizing the input, we could stabilize the output and take advantage of structural sharing.

For example, consider this code:

export function useFiltered(array) {
  const computed = useMemo(() => {
    return cheapOperation(array);
  }, [array]);
  return computed;
}

We can get rid of the memo and guarantee the stability of the output by changing the function to:

export function useFiltered(array) {
  const computed = cheapOperation(array);
  const stable = useStable(computed);
  return stable;
}

The tradeoff is that we now re-compute the result even if the array hasn’t changed. But since the operation is cheap, it doesn’t matter.

This code however has one significant advantage. When the computed value partially changes between renders, the identity of the values that remain the same will be preserved (the same as with React Query)!

Wrapping up

Well, that was fun!

Now, for the big question: should I use it?

It depends.

I found myself using this hook on rare occasions where returning a stable value was important, but I couldn’t simply use a memo because the input wasn’t guaranteed to be stable (eg: an array recreated at each render).

Also, there may be a few edge cases, such as dealing with a variable number of dependencies, where you can’t useMemo (eg: calling useQueries and returning a stable array with the data for each query). useStable doesn’t have such limitations.

Having said that, memos should get the job done most of the time. Also useMemo uses Object.is to compare dependencies and decide whether to run the code, which is cheaper than calling replaceEqualDeep.

Implementing the useStable(value) hook with React Query was originally published in Bits and Pieces on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

In Part 1, we introduced OpenAPI generator and we saw the benefits of using it to generate a fully typed client API.

However, generating a client API is rarely a one-off operation: when you’re working on a new project, the APIs you are consuming are likely to change or receive patches regularly.

So this time, I’ll show you how to build API generation directly into your project. Here, we’ll create a new web application from scratch using a modern stack, but feel free to plug it into your own stack.

Here is the program:

1. Create a web app with Vite, React, and TypeScript
2. Generate the API with OpenAPI Generator
3. Create custom hooks with React Query
4. Consume the API
5. Mock the API with MSW
6. Style with Tailwind CSS (optional)
7. Test with Vitest and Testing Library

1. Create a web app with Vite, React, and TypeScript

OK so, first things first: let’s create a web application (or reuse yours). To make things easier, I’ve decided to stick with a simple Single Page Application (SPA) instead of using a meta-framework like Next.js or Remix.

So for this project, we will use Vite with React and TypeScript. And since we’re on a modern stack, opting for PNPM over NPM makes sense too:

pnpm create vite petstore-app --template react-ts

Done!

🔎 The source code for step 1 is available at: https://github.com/gfox1984/petstore-app/commit/5b8c6c1

2. Generate the API with OpenAPI Generator

2.1. Setup

For this exercise, we will continue using the Pet Store API from Part 1. So go ahead and copy the YAML file into src/api/petstore/api.yaml. It will be the source for generating our client API.

Next, add the OpenAPI Generator to the project with:

pnpm add -D @openapitools/openapi-generator-cli

Then, add a new script to package.json to invoke it:

"scripts": {
  ...  
  "generate-api:petstore": "openapi-generator-cli generate -i ./src/api/petstore/api.yaml -g typescript-axios -o ./src/api/petstore/ --skip-validate-spec --additional-properties=useSingleRequestParameter=true,withoutPrefixEnums=true,enumNameSuffix=,withSeparateModelsAndApi=true,apiPackage=server,modelPackage=model --openapi-normalizer REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true"
}

You must be thinking, “Wow, that’s a heck of a script!”

Indeed! The exact script was written after a lot of trial and error, but it has served me well so far. Let me explain:

• generate-api:petstore is the name of the script used to generate the petstore API. If you want to add another script later on and generate another API (pretty common), follow the same pattern.
• openapi-generator-cli generate invokes the OpenAPI Generator CLI with the generate command
• -i ./src/api/petstore/api.yaml is the OpenAPI file to read from
• -g typescript-axios indicates that we want to use the typescript-axios generator
• -o ./src/api/petstore/ is the output directory for the generated code
• --aditional-properties specifies additional properties that are used to tweak the output:
  useSingleRequestParameter=true generates functions that take a single object in arguments, wrapping all the request parameters. This avoids issues when the number or the order of parameters changes over time.
  withoutPrefixEnums=true and enumNameSuffix= are used to preserve the enum names that are defined in the OpenAPI file
  withSeparateModelsAndApi, used along with apiPackage=server and modelPackage=model, improves readability by splitting the generated API and models into distinct folders
• --openapi-normalizer REFACTOR_ALLOF_WITH_PROPERTIES_ONLY=true is used to prevent issues when using allOf with multiple objects

I hope it makes more sense now. Based on your needs and your API, you might want to adjust those settings. See the documentation for typescript-axios.

Before we wrap this section, let’s not forget to add axios to our list of dependencies (the generated code uses Axios):

pnpm add axios

2.2. Generate

Now that we are set up, we can generate the API using:

pnpm run generate-api:petstore

After the script completes, a bunch of files are generated inside the src/api/petstore folder (see Part 1 for details).

Some of these files aren’t useful, so we can delete them and add them to src/api/petstore/.openapi-generator-ignore:

.gitignore
git_push.sh
.npmignore

We can also add the .openapi-generator folder to our .gitignore :

# api
.openapi-generator

2.3. Export

Finally, I also recommend adding an index.ts file at the root of the src/api folder, where we instantiate and export each API, with a default configuration:

import { Configuration, PetApi, StoreApi, UserApi } from "./petstore";

const configuration = new Configuration();

export const petApi = new PetApi(configuration);
export const storeApi = new StoreApi(configuration);
export const userApi = new UserApi(configuration);

This can be useful in projects where we want to specify a different base URL or use a particular Axios instance.

🔎 The source code for step 2 is available at: https://github.com/gfox1984/petstore-app/commit/13bbaa9

3. Create custom hooks with React Query

Before we start using this brand-new API, we need to determine our fetching strategy. We certainly don’t want to fetch in effects. Since we’re in a SPA, I recommend using React Query, with custom hooks.

So let’s install React Query:

pnpm add @tanstack/react-query

Then, configure the app at src/App.tsx with a QueryClient:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>TODO</QueryClientProvider>
  );
}

export default App;

Now let’s add a custom usePets hook that fetches the list of pets using the findPetsByStatus method of the PetApi.

To do this, create a src/hooks/pet-hooks.ts file with:

import { useQuery } from "@tanstack/react-query";
import { petApi } from "../api";
import { FindPetsByStatusStatus } from "../api/petstore";

const allStatuses: FindPetsByStatusStatus[] = ["available", "pending", "sold"];

export function usePets(status = allStatuses) {
  return useQuery({
    queryKey: ["pet", "findPetsByStatus", status],
    queryFn: async () => (await petApi.findPetsByStatus({ status })).data,
  });
}

The usePets hook takes optional filters in parameters, which it then forwards to the Pet API via the query function (queryFn).

useQuery does all the dirty work for us: updating the loading state, handling errors, caching, etc. And it automatically uses the QueryClient that we configured in the App above. Just make sure you have a unique queryKey for each API and parameters you use in queryFn. The ESLint Query Plugin can help you with that.

🔎 The source code for step 3 is available at: https://github.com/gfox1984/petstore-app/commit/e65b4ba

4. Consume the API

Time to call the API!

Add a component that calls the usePets hook and displays their names in a list at src/components/pets/Pets.tsx:

import { usePets } from "../../hooks/pet-hooks";

export function Pets() {
  const { data: pets } = usePets();

  return (
    <ul>
      {pets?.map((pet) => (
        <li key={pet.id}>{pet.name}</li>
      ))}
    </ul>
  );
}

and use it inside src/App.tsx:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { Pets } from "./components/pets/Pets";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Pets />
    </QueryClientProvider>
  );
}

export default App;

Run the development server with pnpm dev, and voilà:

The good news is that the Pet Store API works out of the box! This is because a valid server URL is provided inside the OpenAPI file. It is pretty rare to note it.

In general, your own API is likely deployed on more than one environment (eg: dev, staging, prod), and you often need to configure its base path first (see point 2.3.).

And that’s if the API is implemented at all! Efficient teams start working on the frontend in parallel with the backend when the API is not yet fully implemented.

Now for the bad news: the data returned by that live API is full of junk. For instance, pets have poor names, and the categories, tags, and photo URLs are just named ‘string’. Developing and styling components requires better data.

🔎 The source code for step 4 is available at: https://github.com/gfox1984/petstore-app/commit/3ae3fa3

5. Mock the API with MSW

When the API you depend on is missing or when you want to test your code against specific data, you might want to use a mock server. You could surely hardcode an object and use it in your component, as a temporary fix. But a mock server will let you write entire apps as if you were working with an actual server. This will give you higher confidence in your code and it will also reduce the amount of changes needed when you’re ready to go live.

5.1. Install

For this, we’ll use the state-of-the-art library for mocking servers called Mock Service Worker (MSW).

pnpm add -D msw

Next, we need to initialize the project, so that MSW can intercept requests when our app runs in the browser:

npx msw init ./public

When asked, answer Y to the question. The output should be:

Copying the worker script at "<your_path>\petstore-app\public"...

Worker script successfully copied!
  - ./public

Continue by describing the network in your application:

https://mswjs.io/docs/getting-started

      INFO In order to ease the future updates to the worker script,
      we recommend saving the path to the worker directory in your package.json.
? Do you wish to save "public" as the worker directory? yes
Updating "msw.workerDirectory" at "<your_path>\petstore-app\package.json"...

5.2. Configure

Now, we’re going to prepare the list of handlers that will be used to handle requests (empty for now).

So, go ahead and create src/mocks/handlers/index.ts with:

export const handlers = [];

Next, create the worker that will intercept those requests, and initialize it with the list of handlers.

For this, create src/mocks/browser.ts:

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers";

export const worker = setupWorker(...handlers);

Finally, we’ll edit our entry point so that the worker starts with the app. Since it’s a mock server, we’ll do it when the app runs in development mode. In the future, we might want to change that to run based on an environment variable (eg: ENABLE_MOCKING).

So, edit src/main.tsx and add this block of code to import and start the worker:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.tsx";
import "./index.css";

if (import.meta.env.DEV) {
  const { worker } = await import("./mocks/browser");
  await worker.start();
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

To validate that everything is configured correctly, run pnpm dev. You should see the following message in the console:

5.3. Mock

Now for the interesting part — mocking our API!

Create some mock Pet objects, and return them when calling the pet/findByStatus endpoint, by pasting this code into a new file at src/mocks/handlers/pet.ts:

import { HttpResponse, http } from "msw";
import { Category, Pet, Tag } from "../../api/petstore";

// mock categories
export const pokemon: Category = { id: 1, name: "Pokemon" };

// mock tags
export const electric: Tag = { id: 1, name: "Electric" };
export const fire: Tag = { id: 2, name: "Fire" };
export const fyling: Tag = { id: 3, name: "Flying" };

// mock pets
export const pikachu: Pet = {
  id: 1,
  name: "Pikachu",
  photoUrls: ["https://upload.wikimedia.org/wikipedia/en/a/a6/Pok%C3%A9mon_Pikachu_art.png"],
  category: pokemon,
  tags: [electric],
};
export const charizard: Pet = {
  id: 2,
  name: "Charizard",
  photoUrls: ["https://upload.wikimedia.org/wikipedia/en/1/1f/Pok%C3%A9mon_Charizard_art.png"],
  category: pokemon,
  tags: [fire, fyling],
};

// mock handlers
export const handlers = [
  http.get<never, never, Pet[]>("*/pet/findByStatus", () =>
    HttpResponse.json([pikachu, charizard])
  ),
];

As you can see, each mock object is typed using one of the generated interfaces. The mock handler that intercepts the request is also typed: http.get<never,never,Pet[]>, meaning that it’s a GET method, with:

1. no parameters (never)
2. no body (never)
3. an array of Pets in response (Pet[])

Although these types are optional, they make sure that we comply with the API specification and help in preventing errors.

So, we now have mock handlers for our endpoints (well, technically we only have one, but we have to start somewhere!). The next step is to add them to the list at src/mocks/handlers/index.ts:

import { handlers as petHandlers } from "./pet";

export const handlers = [...petHandlers];

When this is done, run the development server (pnpm dev). The app is now showing our mock data!

The cool thing is that mock responses can be inspected directly inside the Network tab using the dev tools as if they were regular responses.

5.4. Going further

In this article, we’ve mocked a simple GET request. But other methods could be mocked too in a similar way. We could also customize responses based on the parameters we receive in the handler.

The official documentation has a simple example that implements CRUD operations with mock handlers:

Describing REST API

🔎 The source code for step 5 is available at: https://github.com/gfox1984/petstore-app/commit/7036eb8

6. Style with Tailwind CSS (optional)

This section is optional, so feel free to skip it. But since we’re having fun with our mock data, let’s wrap this up and display those pets in a nicer way!

Modern apps are built with Tailwind CSS (controversial). So we’ll configure Tailwind as per their Vite guide, and use it for styling.

First, add the required libraries, and initialize the project with:

pnpm add -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Then, update the freshly created tailwind.config.js file with:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

And finally, replace the content of src/index.css with:

@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind is now set up.

Let’s update the markup of our Pets component with it! I don’t know about you, but I’m not fluent in Tailwind… So one way to get started is to use v0 by Vercel to generate some code. Once you have a version you’re happy with (or close enough), you can update the component at src/components/pets/Pets.tsx. Mine looks like this:

import { usePets } from "../../hooks/pet-hooks";

export function Pets() {
  const { data: pets } = usePets();
  return (
    <ul className="grid md:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-6 gap-6 m-6">
      {pets?.map((pet) => (
        <li
          key={pet.id}
          aria-label={pet.name}
          className="group rounded-lg overflow-hidden relative shadow-md"
        >
          <img
            alt={pet.name}
            className="object-contain w-full aspect-[3/2] bg-slate-50"
            src={pet.photoUrls[0]}
          />
          <div className="p-4">
            <h3 className="font-semibold text-lg">{pet.name}</h3>
            <p className="text-sm text-gray-500">{pet.category?.name}</p>
            <div className="flex gap-2 flex-wrap mt-4">
              {pet.tags?.map((tag) => (
                <span
                  key={tag.id}
                  className="rounded-lg bg-gray-100 px-2 py-1 text-xs"
                >
                  {tag.name}
                </span>
              ))}
            </div>
          </div>
        </li>
      ))}
    </ul>
  );
}

Note that I also added some aria-label for accessibility (see Accessibility: the selfish reasons why developers should care about it).

Now the page should look something like this:

Better 😌

🔎 The source code for step 6 is available at: https://github.com/gfox1984/petstore-app/commit/da52b5e

7. Test with Vitest and Testing Library

Testing time! The part you’ve all been waiting for!

More seriously: we’ve built a strong, fully-typed app. What we need now are strong tests that will ensure:

1. The application behaves as expected
2. We have a safety net when we refactor

I know that some people have an allergic reaction to testing. Maybe they had a bad experience in the past. Maybe they don’t want to invest time in testing. Today I want to show you that testing doesn’t have to be time-consuming or painful.

7.1. Install

Let’s start with the setup, which is the painful part… But luckily, you only need to do it once.

I decided to use Vitest instead of Jest. This will actually take a lot of the pain away, with minimal trade-offs… We’ll also use Testing Library to help us write good tests.

For this, add the following dev dependencies:

pnpm add -D vitest @testing-library/react @testing-library/jest-dom @types/react-dom jsdom

Next, add a test script to package.json:

"scripts": {
  ...
  "test": "vitest"
}

Finally, edit vite-config.ts with:

/// <reference types="vitest" />
// ...
export default defineConfig({
  // ...
  test: {
    environment: "jsdom",
    setupFiles: ["./src/vitest-setup.ts"],
  },
});

and create src/vitest-setup.ts:

import "@testing-library/react";
import "@testing-library/jest-dom/vitest";

import { afterEach } from "vitest";
import { cleanup } from "@testing-library/react";

afterEach(() => {
  cleanup();
});

7.2. Configure

The secret of good tests is a good configuration. One that will make our tests easy to write and to maintain, while staying as close as possible to reality.

In our app, like in most apps, we use a bunch of top-level providers to configure the tools we use in the components. Our app is still small, and it only uses one provider: QueryClientProvider. Yet, if we want the tested components to run in the same conditions as in the app, we need to make sure that the test suite is configured to use such providers.

In its setup docs, Testing Library advises replacing the built-in render function with a custom one, which wraps the tested component with our providers. So let’s add a QueryClientProvider to our custom render function, which we’ll set up according to TanStack Query Docs.

Create a src/utils/test-utils.tsx with this code:

import React, { ReactElement } from "react";
import { render, RenderOptions } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const AllTheProviders = ({ children }: { children: React.ReactNode }) => {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
      },
    },
  });
  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
};

const customRender = (
  ui: ReactElement,
  options?: Omit<RenderOptions, "wrapper">
) => render(ui, { wrapper: AllTheProviders, ...options });

export * from "@testing-library/react";
export { customRender as render };

Finally, we also want to make sure that the mock server we created earlier is used to respond to network requests in the test suite. To do that, simply create a src/mocks/node.ts file with:

import { setupServer } from "msw/node";
import { handlers } from "./handlers";

export const server = setupServer(...handlers);

Then, add this setup + cleanup code at the end of src/vitest-setup.ts:

// ...
import { beforeAll, afterEach, afterAll } from "vitest";
import { server } from "./mocks/node";

// ...
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

We can now throw any component into the test suite and expect it to work out of the box. This configuration will dramatically reduce the number of mocks we use in our tests and, by extension, those tests will also be less brittle.

7.3. Test components

Enough talking, let’s write some tests for our Pets component!

Add a src/components/Pets.test.tsx file with this test case to ensure our component renders:

import { it } from "vitest";
import { Pets } from "./Pets";
import { render } from "../../utils/test-utils";

it("renders", () => {
  render(<Pets />);
});

Run it with pnpm test and check the terminal:

✓ src/components/pets/Pets.test.tsx (1)
   ✓ renders
 
 Test Files  1 passed (1)
      Tests  1 passed (1)

The test passes 😅!

Nice work, but a bit too easy. We want to make sure it renders the right things! Since we’ve configured our mock server to return some pre-defined pets, we want to assert that those pets are effectively rendered.

For this, add a new test case to the file:

import { expect, it } from "vitest";
import { Pets } from "./Pets";
import { render, screen } from "../../utils/test-utils";

it("renders", () => {
  render(<Pets />);
});

it("shows the list of pets", async () => {
  render(<Pets />);
  expect(screen.getByRole("listitem", { name: "Pikachu" })).toBeInTheDocument();
  expect(screen.getByRole("listitem", { name: "Charizard" })).toBeInTheDocument();
});

Run it and…

FAIL  src/components/pets/Pets.test.tsx > shows the list of pets
TestingLibraryElementError: Unable to find an element with the text: Pikachu. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.

…FAIL!? 😱

Do you get why?

Our test suite is configured to behave like the real application. So just like in real life, network requests are asynchronous. Therefore, we need to wait until the request has completed before asserting on the rendered pets.

That’s for the technical explanation. In practice, the network request is an implementation detail. And you don’t want to test against an implementation detail (unless you want to end up hating tests!). So what you do instead is wait until the expected element appears on screen to make the assertion. Testing Library provides an asynchronous findBy query for that.

So, to make the test pass, prefix the test function with async and replace the first occurrence of screen.getByRole with await screen.findByRole:

it("shows the list of pets", async () => {
  render(<Pets />);
  expect(await screen.findByRole("listitem", { name: "Pikachu" })).toBeInTheDocument();
  expect(screen.getByRole("listitem", { name: "Charizard" })).toBeInTheDocument();
});

Now the test passes 🎉

 ✓ src/components/pets/Pets.test.tsx (2)
   ✓ renders
   ✓ shows the list of pets

 Test Files  1 passed (1)
      Tests  2 passed (2)

7.4. Test hooks (optional)

Depending on your testing strategy, you might also want to check that your custom hooks return the expected data. This is not strictly needed since the previous test already covers this (test coverage will confirm this). But for the sake of this exercise, let’s add a test case for the usePets hook.

Testing Library has a renderHook function for this, but we don’t want to use it directly. Instead, we’ll modify src/utils/test-utils.ts and replace the renderHook function with a custom one that wraps the tested hook with our providers, just as we did earlier with the render function:

import { render, renderHook, RenderOptions } from "@testing-library/react";

//...

const customRenderHook = <Result, Props>(
  render: (initialProps: Props) => Result,
  options?: Omit<RenderOptions, "wrapper">
) => renderHook(render, { wrapper: AllTheProviders, ...options });

//...

export { customRenderHook as renderHook };

We are now ready to assert that our usePets hook returns the expected data. Following the recommendations from React Query (which we use in the hook), let’s create a src/hooks/pet-hooks.ts file with:

import { describe, expect, it } from "vitest";
import { renderHook, waitFor } from "../utils/test-utils";
import { usePets } from "./pet-hooks";
import { charizard, pikachu } from "../mocks/handlers/pet";

describe("usePets", () => {
  it("returns a list of pets", async () => {
    const { result } = renderHook(() => usePets());
    await waitFor(() => expect(result.current.isSuccess).toBe(true));
    expect(result.current.data).toEqual([pikachu, charizard]);
  });
});

And then run the tests again :

 ✓ src/hooks/pet-hooks.test.ts (1)
 ✓ src/components/pets/Pets.test.tsx (2)

 Test Files  2 passed (2)
      Tests  3 passed (3)

All pass!

Testing hooks can be useful when you want to cover some particular use cases or edge cases that you don’t necessarily verify when testing your components.

🔎 The source code for step 7 is available at: https://github.com/gfox1984/petstore-app/commit/edd8454

Conclusion

I hope that you enjoyed this tutorial and that it will help you make the most of OpenAPI. The topics covered here can significantly benefit your team by allowing it to start working on the frontend code sooner than previously possible. No more waiting for the backend to be ready!

As a developer, fully typing your client API is not only a great way to reduce bugs, but it will also boost your productivity thanks to better code completion. Additionally, it will simplify testing if you invest in a good setup.

Applications that are fully typed and tested not only stand the test of time better but also provide greater assurance when it comes to refactoring.

Coming up in Part 3

Rejoice! There will be a Part 3!

Generating a good client API requires a good specification in the first place, so I’ll share some advice to optimize your OpenAPI file for optimal code generation. Plus, I’ll provide tips to enhance your developer experience and more!

You know what to do: follow me and stay tuned!

Stackademic 🎓

Thank you for reading until the end. Before you go:

• Please consider clapping and following the writer! 👏
• Follow us X | LinkedIn | YouTube | Discord
• Visit our other platforms: In Plain English | CoFeed | Differ
• More content at Stackademic.com

Fully typed Web Apps with OpenAPI (Part 2) was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.

About two years ago, I wrote a story on Medium about how I stay updated with React (and frontend development in general), which proved fairly popular:

How I Stay Up to Date with React (and Front-End Development)

While the story is still relevant today, I felt that it needed a refresh. I’m now following more people on Twitter, and I use some resources more than others.

Also, 2024 promises to be a big year: React is due to receive some upgrades, more frameworks are starting to adopt React Server Components (RSC), and there is now a consensus that useEffect should be avoided like the plague. Oh, and what about AI? Vercel has been blowing our minds with v0 and Generative UI since the year started.

So, if you don’t want to be left out, I have compiled a list of resources that will help you stay in the loop:

T̵w̵i̵t̵t̵e̵r̵ 𝕏

𝕏 is more than ever the place to be if you want to stay updated with React. The great exodus announced when Elon Musk bought the social network never happened. I even had to add a “bonus” section to my top 5 because of the amount and quality of influential developers on the platform:

Dan Abramov²

Nobody knows what happened to Dan the 1st. He became invisible on 𝕏 after he quit Meta. But fear not, he’s back with Dan 2, stronger than ever. Dan is on a mission to educate people on React Server Components (RSC). And if there’s one person on Earth that can do that, it’s him.

Kent C Dodds

Kent is one of the most experienced React developers out there. He’s produced an insane amount of training content, worked at PayPal and Google, and co-founded Remix. He’s even managed to make developers enjoy testing web apps (partly thanks to Testing Library).

Dominik Dorfmeister

Dominik 🔮 on Twitter: "react-query doesn't do data-fetching - it's an async state manager based on promises, so you don't need to copy data from react-query into another state manager. I have multiple blogposts and a talk on just this topic 😂 / Twitter"

react-query doesn't do data-fetching - it's an async state manager based on promises, so you don't need to copy data from react-query into another state manager. I have multiple blogposts and a talk on just this topic 😂

Everybody knows and loves React Query! Dominik is the guy behind it. He’s very active on 𝕏 and has a great blog too: https://tkdodo.eu/.

Cory House

Cory House on Twitter: "React has over a dozen popular third-party state libraries. React Query, Zustand, Redux, Jotai, Mobx, etc.Prediction: Third-party React state libraries will become less relevant in 2024.Why? I see two things "eating" this space:1. Routers are becoming state managers.... / Twitter"

React has over a dozen popular third-party state libraries. React Query, Zustand, Redux, Jotai, Mobx, etc.Prediction: Third-party React state libraries will become less relevant in 2024.Why? I see two things "eating" this space:1. Routers are becoming state managers....

I didn’t even realize how much I liked Cory’s tweets until I looked at my list of bookmarks. Cory is an independent consultant. His tweets are spot-on and full of good advice!

Theo Browne

Theo - t3.gg on Twitter: "If you really need to build a "Single Page App" and can't server render for some reason, this is probably your best bet https://t.co/b9C92VRLtL / Twitter"

If you really need to build a "Single Page App" and can't server render for some reason, this is probably your best bet https://t.co/b9C92VRLtL

Theo is more well-known for this YouTube channel (read on), but his 𝕏 account is well worth it too—a mix of amusing shit posts and overreactions to the latest news in the frontend world. But behind the agitation, Theo is an amazing hardworking React developer.

Bonus Track

OK, I could go on like this forever. Tech Twitter is the place to be when you’re a frontend developer. But let’s cut it short and wrap this with a few more people.

Whether you like Next.js or not, Vercel is always going to be on top of the React game, and its CEO, Guillermo Rauch, is here to prove it. But maybe you’re more into Remix? Then Ryan Florence is your guy. And what about Tanner Linsley, creator of the TanStack? Let’s not forget Daishi Kato, the author of the only state libraries you want to use in 2024 (Zustand, Jotai,…). Finally, I wanted to mention Matt Pocock, the TypeScript wizard (he also has a newsletter and free tutorials).

Okay, I couldn’t conclude without mentioning @0xca0a (☄︎)… His tweets probably won’t help you pay your bills (who knows), but you‘ll be amazed to see what React Three Fiber can achieve:

Web

I always love a good read and I like to learn by the book. Here are my few favorite websites for that:

React.dev

React

This may be obvious, but the best resource to learn React is the official React website… The Learn section contains plenty of interactive examples, and I cannot think of a better way to learn React. The website is accessible to all levels, from beginner to advanced developers.

Once you’ve read and understood the advanced topics, you will probably be better than 80% of the React developers out there. Dan Abramov himself wrote these docs, so it’s a joy to read and you’ll easily get there if you’re motivated enough.

Also, don’t forget to keep an eye on the blog posts to know what’s cooking.

Frontend Mastery

Navigating the future of frontend

I’m so glad I found this website back in 2022 in my original story. Frontend Mastery has helped me navigate through what was happening in the frontend world since then, and in particular with how to manage state and implement composition.

It’s easy to fall for biased fanboy opinions when you read tweets and blog posts (although this is also part of the fun 😁). But Frontend Mastery always keeps a humble, high-level, detached eye towards frontend development. Of course, React will always have a good spot on Frontend Mastery, but so far, it has never been promoted king.

I highly recommend this website if you like deep dives and you want to up your game.

Epic Web

Epic Web Dev Articles

Epic Web aims to teach the world about modern full-stack web development. Since it’s Kent C Dodds’ project, you already know it’s going to be good! But this time, he has teamed up with several top developers, such as Artem Zakharchenko (creator of MSW), to produce amazing content.

The articles, as well as some tutorials, are free to access. But in case you or your employer have a thousand bucks to spare, consider buying the full course (I haven’t yet, but I’m working on it 😉).

Newsletters

Newsletters are a great way to stay updated and discover things you may not have thought of. Here my favorite two:

Bytes: Your Weekly Dose of JavaScript

Join Bytes - Your weekly dose of JavaScript

One of the best JavaScript newsletters! Bytes sends its newsletter twice a week, which is A LOT of content to digest. But luckily, the newsletter is an easy read and it never fails to make me smile.

Here is an extract from their latest “OSScars” winners:

Best Independent Film: htmx. Like most indie films, everyone loves to talk about how great htmx is, despite the fact that they’ve never actually used it. That’s how you know the htmx team’s extended PSYOP meme-based marketing campaign is working.

And if you’ve missed the newsletter or you’re just curious about it, see the Bytes Archive.

Medium

Of course, I had to include Medium! You found my story on Medium, and I bet it’s not your first time here. The platform has a lot of stories written by authors like you and me who like to share their knowledge on the technologies they work with.

Some content can only be found on Medium. For example, since I’ve had to work with Micro-frontends and Module Federation, I found that the main contributor in the domain, Zack Jackson, publishes all his updates and tutorials here.

Many major companies, such as Netflix Technology Blog, also publish their blog on Medium. I find it always interesting to read about how big corps do technology at scale.

So make sure to follow the authors you like and subscribe to the newsletter. The newsletter is tailored to you, with the people and topics you like. The more you read, the better it gets.

Video

I’ll be honest, I don’t watch much video as I find it hard to sit in front of a screen for 10+ minutes without distraction. But I happen to watch some, and I know many of you like this format. So here it is:

Theo Browne

Yes, Theo, again. This time, in his natural habitat: YouTube. If anything happens in the React World, you’ll probably see a video of Theo about it in the next 48 hours (or less). You might find that a few of his videos are just plain rants, but he always has a point, whether you agree or not.

Jack Herrington

Jack is the other big name on YouTube if you like frontend development. Just like Theo, Jack covers all the latest technologies, with a hands-on approach. He’s also an expert on some niches, such as Micro Frontends, and his content has become the reference in the domain.

Ben Holmes

He’s one of the new kids on the block. Don’t be misled by his juvenile look, Ben is a lead engineer at Astro and he probably knows more React than we do. He’s published some impressive videos on React Server Components, but Ben’s also posting some shorts on YouTube and TikTok if you just want your daily fix.

Conclusion

If you made it up here, you might feel a bit overwhelmed! Don’t worry, it’s normal, nobody can’t digest that amount of information. What matters is that you find your way and frequency to stay informed. Don’t be pressured to try out or use everything you read about. Let the hype settle and see what sticks.

You’ll be amazed to see what a few minutes spent reading each week will do to you. Things will start picking your curiosity. Without noticing, you will learn and improve your skills, and be more prepared for the next big thing to happen.

Finally, remember to share your best finds with your peers! It’s easier and more fun when you have a community around you.

Challenges & solutions

React legend Kent C. Dodds wrote about the challenges and benefits of fully typed web apps in the Epic Web series. If you haven’t read it yet, you should give it a go, it’s well worth it.

One of the biggest pain points in web development is making network requests and processing their response. In the past years, new technologies have emerged to make this task easier and safer.

For example, if you use TypeScript in both your frontend and backend, then tRPC is a great candidate to share your types between the two. tRPC has been popularized by the T3 Stack created by the famous Youtuber Theo.

Zod is another library that is commonly used with tRPC, which you can also use on its own. Zod allows you to define schemas to validate your data and infer types. This is great for validating the input and output of your APIs and keeping your app fully typed.

What about OpenAPI?

All of this is great, but if you’ve worked in a medium or a large company, you know that the backend and frontend are often developed by different developers, using different technologies. So forget tRPC. Maybe you could use Zod. But chances are your company already uses OpenAPI (formerly known as Swagger) to document its services.

Yes, OpenAPI documentation looks great and can be understood by all the stakeholders, whether they are technical people or not. But OpenAPI can do much more. Yet, only a few companies are making the most of it.

How many frontend developers out there are still translating OpenAPI docs to code by hand? Not only that is tedious, but it is also very error-prone. Surely there must be a better way!

Introducing OpenAPI generator

Enter the magical world of OpenAPI generator! Generators allow you to generate a variety of contents from your OpenAPI documents:

• Client code that you can use to consume a service
• Server code that you can use to implement a service
• Human-friendly documentation
• Schemas used to generate a database or describe a service

In this article, we’ll focus on client generators.

Example

Let’s use a concrete example. Imagine that you are the owner of an online pet store and that your service is described in this OpenAPI document: petstore.yaml. If you’ve read some OpenAPI documentation before, you won’t find it very original… But it is still a good example.

This document defines a few operations: add a pet, update its details, create orders, manage users, etc… Even for the non-initiated, the OpenAPI format is fairly easy to read and understand. That’s why developers and stakeholders like it so much.

For example, here is the definition of the endpoint used to add a pet to the store:

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: ''
      operationId: addPet
      responses:
        '200':
          description: successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'
      requestBody:
        $ref: '#/components/requestBodies/Pet'

and the definition of the data it refers to:

components:
  requestBodies:
    Pet:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Pet'
        application/xml:
          schema:
            $ref: '#/components/schemas/Pet'
      description: Pet object that needs to be added to the store
      required: true
  schemas:
    Pet:
      title: a Pet
      description: A pet for sale in the pet store
      type: object
      required:
        - name
        - photoUrls
      properties:
        id:
          type: integer
          format: int64
        category:
          $ref: '#/components/schemas/Category'
        name:
          type: string
          example: doggie
        photoUrls:
          type: array
          xml:
            name: photoUrl
            wrapped: true
          items:
            type: string
        # more...

As a frontend developer, at this point, you could roll up your sleeves, grab a coffee, and start translating this document into code. With a fair amount of copy/pasting, you should get the job done in a few hours… not to mention the cost to your sanity and the few mistakes nobody spotted on the way.

Or you could use a generator.

From documentation to Code!

Let’s start with the unpleasant part… OpenAPI generator is implemented in Java (🤷), so you first need to install Java on your machine. But beware, there is a catch… The latest OpenAPI generator requires Java 11, which only comes with the full Java Development Kit (JDK) (160MB+) (Oracle stopped shipping the lightweight Java Runtime (JRE) at version 8 (🤷🤷).

Once you’re done, you can either stick with Java or use your favorite package manager to run the generator. My preferred option is to use a package manager, as it will allow us to integrate the generator into our existing projects later on.

The first step is to install the CLI package:

npm install @openapitools/openapi-generator-cli -g

Then, run it on the downloaded API, with the chosen generator. Let’s say our project uses Axios and TypeScript. We can use the following command line to generate the code into the petstore folder:

npx @openapitools/openapi-generator-cli generate -i petstore.yaml -g typescript-axios -o petstore

And if you don’t like Axios or Typescript (🤔), there are other generators available, see the complete list here.

The generated petstore folder contains a bunch of files:

.openapi-generator
.gitignore
.npmignore
.openapi-generator-ignore
api.ts
base.ts
common.ts
configuration.ts
git_push.sh
index.ts

The interesting part is located inside api.ts. The other files can be ignored for now (*ignore and .sh files aren’t useful unless you want to publish the folder to its own repo, and the other files only contain utility code).

If you open api.ts in your editor, you’ll see plenty of well-documented TypeScript interfaces, such as:

/**
 * A pet for sale in the pet store
 * @export
 * @interface Pet
 */
export interface Pet {
    /**
     * 
     * @type {number}
     * @memberof Pet
     */
    'id'?: number;
    /**
     * 
     * @type {Category}
     * @memberof Pet
     */
    'category'?: Category;
    /**
     * 
     * @type {string}
     * @memberof Pet
     */
    'name': string;
    
    // more...
}

Pretty neat! That’s a lot of weight taken away from the developer’s shoulders. And the quality of the output is probably greater than what you would have achieved by hand.

But the best part is yet to come. If you scroll further down that file, you’ll find fully implemented methods that you can use to call your endpoints:

 /**
 * PetApi - object-oriented interface
 * @export
 * @class PetApi
 * @extends {BaseAPI}
 */
export class PetApi extends BaseAPI {
    /**
     * 
     * @summary Add a new pet to the store
     * @param {Pet} pet Pet object that needs to be added to the store
     * @param {*} [options] Override http request option.
     * @throws {RequiredError}
     * @memberof PetApi
     */
    public addPet(pet: Pet, options?: RawAxiosRequestConfig) {
        return PetApiFp(this.configuration).addPet(pet, options).then((request) => request(this.axios, this.basePath));
    }

    /**
     * 
     * @summary Deletes a pet
     * @param {number} petId Pet id to delete
     * @param {string} [apiKey] 
     * @param {*} [options] Override http request option.
     * @throws {RequiredError}
     * @memberof PetApi
     */
    public deletePet(petId: number, apiKey?: string, options?: RawAxiosRequestConfig) {
        return PetApiFp(this.configuration).deletePet(petId, apiKey, options).then((request) => request(this.axios, this.basePath));
    }

    /**
     * Multiple status values can be provided with comma separated strings
     * @summary Finds Pets by status
     * @param {Array<FindPetsByStatusStatusEnum>} status Status values that need to be considered for filter
     * @param {*} [options] Override http request option.
     * @throws {RequiredError}
     * @memberof PetApi
     */
    public findPetsByStatus(status: Array<FindPetsByStatusStatusEnum>, options?: RawAxiosRequestConfig) {
        return PetApiFp(this.configuration).findPetsByStatus(status, options).then((request) => request(this.axios, this.basePath));
    }

    // more...
}

Yep. Fully typed APIs. All of this was generated from a single OpenAPI file 🤯

Would you like to add a Pet to the store? No problem:

const added = await new PetApi().addPet({
  name: 'Pikachu',
  photoUrls: ['https://example.com/pikachu.jpg'],
  category: {
    id: 123,
    name: 'Pokemon'
  },
  tags: [{
    id: 123,
    name: 'Electric'
  }],
});

If you dig into the generated code, you’ll see that it takes care of validating the parameters, setting the right verb and headers, serializing the data if needed, sending the request with Axios, and returning the result, complete with the expected type.

And in case the API or the server required some configuration, or you wanted to use your own Axios instance for example, the generated code has got you covered too:

const api = new PetApi(
  new Configuration({ accessToken: "eyJ0eXAiO", apiKey: "key-abc" }),
  "https://api.example.com",
  myAxios
);

You’re welcome.

OpenAPI in the real world

The quality of the generated API will depend on the quality of your documentation. The petstore.yaml file used in this example is good, if not perfect. Yours probably won’t be as good.

However, the best way to improve your OpenAPI documentation is to start using it to generate code. This will allow you to identify gaps and fix them until you’re happy with the output. By experience, I have seen great improvements to the OpenAPI documentation once developers started using it for code generation, leading to greater adoption (not to say addiction) on both the backend and frontend sides.

Generated APIs can save you a lot of time. But they also eliminate a whole category of bugs thanks to type safety. When your API eventually changes, TypeScript promptly lets you know what parts of the code need updating.

Coming up in part 2

In the next part, we’ll see how to integrate a generator into your existing project and make the best use of the CLI options.

I’ll also show you how to create reusable React hooks to query and cache the data. And if you like it, I might even teach you how to mock the server, so that you can start creating and testing your pages even before the service is implemented 😮

So when you’re ready, head this way:

Fully typed Web Apps with OpenAPI (Part 2)

Stackademic 🎓

Thank you for reading until the end. Before you go:

• Please consider clapping and following the writer! 👏
• Follow us X | LinkedIn | YouTube | Discord
• Visit our other platforms: In Plain English | CoFeed | Differ
• More content at Stackademic.com

Fully typed Web Apps with OpenAPI (Part 1) was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.