DEV Community: Anik

Mocking Back-ends for React Apps with MirageJS

Anik — Mon, 11 Oct 2021 22:00:51 +0000

Seven tips to help you avoid bottlenecks and future-proof your mock back-end

⚠️ Disclaimer
This article assumes you have some familiarity with the React framework, and Javascript and Typescript fundamentals. It also assumes you are comfortable with concepts and terms related to relational databases.

What led me to consider Mirage
(1) Don't put everything in one file
(2) Start with a plan
(3) Define Typescript interfaces for models
(4) Consider a "hybrid" approach for generating realistic seed data
(5) Split up and aggregate route handlers
(6) Create API client functions for UI components
(7) Set up passthroughs and a unique namespace for mock routes
Closing thoughts

What led me to consider Mirage

I recently helped create a high-fidelity React-based prototype for a new product still in its early stages. We were not entirely certain if the product would solve the problem it was intended to solve for our customers. We needed feedback and, in order to get that feedback, we needed to put something in front of potential customers that wasn’t merely a slideshow or clickable mockup, something closer to the “real thing”. We wanted them to be able to explore and interact with the prototype in a much more realistic manner than they otherwise could if it were just a slideshow or mockup with limited interaction targets, and a strict, pre-determined “flow”. This would ultimately help us decide whether we could continue building out the rest of the application as-is, or if we needed to go back to the drawing board.

Building such a prototype, without an actual back-end, would require significantly fewer resources and would therefore pose less of a risk to our organization in terms of cost, should the concept prove to be unviable. But how does one go about building a UI prototype with realistic data, and simulating the ability to interact with and modify said data, without an actual back-end? This is the question that first led me to consider a library like Mirage.

Mirage (and other tools like Mirage) allow us to mock back-ends and APIs for JavaScript applications. With a mock data layer, fixed and/or dynamically generated mock data, and an accompanying API, you can build your client application, simulate the accessing and modifying of data, and even run tests, as though the back-end and API already exist.

I don’t plan on using this article exclusively to try and convince you to use Mirage on a future project. I think the MirageJS documentation already makes a great case as to the “why”. The documentation also has excellent step-by-step guides and tutorials, so this article is not a “getting started” guide, either. Instead, I plan to use this opportunity to share what I feel are some good “best practices”, drawn from my own experiences.

Don’t put everything in one file

To start off, it’s entirely possible to define and configure the entire mock back-end in one massive function inside a server.ts file (or server.js file, if you’re not using Typescript). In fact, if you follow Mirage's tutorials, that's basically what they’ll have you do initially: all of the code for the mock back-end — models, routes and route handlers, fixtures, seed data factories, and everything else — in one file. However, I've found that this approach becomes cumbersome in the long-run, especially once the mock back-end becomes more complex and once you start adding custom route handlers.

Here is how I like to organize my Mirage code:

📁 src/ (root directory of React app)
 ├── 📁 components/   ─┐
 ├── 📁 hooks/         ├── React app components and
 ├── 📁 ...           ─┘    other client app code
...
 └── 📁 mock-api/
      ├── 📁 models
      ├── 📁 factories
      ├── 📁 routes
      ├── 📁 serializers
      ├── 📁 clients
     ...
      ├── 📄 server.ts
      └── 📄 index.ts

I’ll be going over the individual pieces in more detail shortly, but here’s a general summary:

I keep all of the Mirage mock back-end code inside a 📁 mock-api (or similarly named) directory.
I keep the main 📄 server.ts file (where my Mirage server instance generator function is defined) directly inside this directory.
The 📁 models directory is where I store Typescript interfaces for all data models, as well as other interfaces, enums, and other type declarations related to the data.
The 📁 factories directory contains sample data fixtures for seeding the mock database with initial sample data. It also contains any factories responsible for generating seed data with custom generator functions. I could have also named this folder "data".
The 📁 routes directory contains code that implements custom route handlers and registers routes with the server instance. For instance, if I defined a custom HTTP GET endpoint that allowed a list of items to be searched, sorted, and filtered, I would place that code inside this directory. The 📁 serializers directory is for any custom data serializers that I’ve defined, in case I find it necessary to serialize certain data in a specific way after processing queries. The topic of serializers is beyond the scope of this article, but the Mirage documentation has plenty of information on the subject.
The 📁 clients directory contains API client functions that simplify the process of sending API requests from the front-end, and reduce the amount of repeated boilerplate code I have to write when doing so.

The advantages of splitting out code in this fashion should be fairly self-explanatory, but two things in particular stand out to me:

When committing changes to the Mirage code, diffs will be far easier to understand and interpret. Instead of viewing a hodgepodge of changes within one massive file, changes will appear more surgical, split out over several files. It should be easier to tell what changed and what didn’t, and easier to spot mistakes.
Maintenance becomes easier. Avoid having to scroll up and down an enormous file to make several related changes or to compare two or more related things. It’s much easier to locate something by pulling up a separate, aptly-named file, than by hunting for it inside thousands of lines of code.

Start with a plan

For Mirage, “models” (similar to tables in a relational database) are the building blocks of the mock back-end; they define the schema on which everything stands. Before getting too far ahead, I recommend taking some time to plan out the models and relationships between those models.

It’s very easy to get started with Mirage and I initially made the mistake of running before I could walk. I hastily defined the models and relationships thereof, and started building the mock back-end and the various route handlers. I soon discovered that I had overlooked some crucial aspects of the schema, and ended up spending hours reworking the models, seed data, and other related things.

In the example below, I’ve defined some models for a hypothetical application's mock back-end, via the models config property.

import { createServer, Model } from "miragejs";

export function makeServer() {
  const server = createServer({
    models: {
      product: Model,
      order: Model,
      orderItem: Model,
      tag: Model,
      user: Model,
      userFavorite: Model,
    },
  });
  return server;
}

These models are not very useful at the moment. As you may suspect just by reading their names, there are some relationships between these distinct models. Multiple OrderItems, for instance, comprise and are related to one Order. An item marked as a UserFavorite is related to a particular Product and User. To see the relationships between these models more clearly, let’s first create a simple schema:

This, of course, is a highly-simplified, contrived example. The benefits of such preparation become more obvious when grappling with complex, realistic schemas. The Mirage API provides easy ways to define relationships (one-to-many, many-to-one, etc.) between models, using the belongsTo() and hasMany() helpers. Let’s configure our models to reflect those relationships, now that we know what they are:

export function makeServer() {
  const server = createServer({
    models: {
      product: Model.extend({
        tag: hasMany(),
      }),
      order: Model.extend({
        user: belongsTo(),
      }),
      orderItem: Model.extend({
        order: belongsTo(),
        product: belongsTo(),
      }),
      tag: Model.extend({
        product: hasMany(),
      }),
      user: Model.extend({
        userFavorite: hasMany(),
      }),
      userFavorite: Model.extend({
        user: belongsTo(),
        product: belongsTo(),
      }),
    },
  });
  ...
}

Mirage will automatically assign primary and foreign keys for each model, based on how you’ve configured the relationships. When accessing UserFavorite data in the mock database, for instance, you’ll find that each UserFavorite record now has userId and productId fields that serve as foreign keys that correspond to the primary keys of particular instances of a User and a Product in the database, respectively.

Define Typescript interfaces for models (if your project implements Typescript)

For obvious reasons, if your application does not implement Typescript this tip probably won’t be very useful in your particular case.

In the previous example, the models we defined will allow us to take advantage of Mirage’s object-relational mapping (ORM) capabilities. When running queries on the mock database, we will serialize the results into JSON and convey them back to the React app, simulating exactly what would happen with an actual back-end with a web API. The JSON result must then be deserialized in the client app before the data can be processed by the React components. Assuming the React app implements Typescript, wouldn’t it be nice if the components had access to interfaces and types that defined the structure of the data? Plus, if certain components needed to pass around data via props, we could use said interfaces to declare prop types.

The schema we defined earlier will come in handy for this. We can now easily declare Typescript interfaces for each of the models in our mock back-end. Let’s start with the Tag and Product models:

We know there’s a many-to-many (both-ends-optional) relationship between products and tags, as one tag could be associated with one, multiple, or zero products, and each product could be associated with one tag, many tags, or no tags at all. Actually, because we suggested a many-to-many relationship in the model configuration, Mirage will automatically add a property to each Tag in the database that tracks all of the related products associated with that tag. But we don’t necessarily want an array of Products for each Tag object, as far as our client app is concerned.

The Tag model’s corresponding interface is pretty simple. As for the Product interface, each product object will contain an array of tags. Each member in this array is a Tag object.

Now let’s say our hypothetical UI will display products in a list, with each individual product shown as a card containing that product’s information. Let’s say that these cards are rendered using some ProductCard component:

interface ProductCardProps {
  name: string;
  seller: string;
  price: number;
  type: string;
  tags: string[];
}
function ProductCard(props: ProductCardProps) {
  return (
    ...
  );
}

In another part of the UI, a list of “recommended products” is displayed, with minimal information about each product. This RecommendedProduct component might be used to display each product snippet:

interface RecommendedProductProps {
  name: string;
  seller: string;
  price: number;
}
function RecommendedProduct(props: RecommendedProductProps) {
  return (
    ...
  );
}

There could be many more components like these in the app, each displaying or processing product data in some form or fashion. I’ve purposefully omitted their implementation details, because right now we’re more concerned with their props APIs. The props interfaces shown are built to match only the current structure of product data in the mock back-end, and they feature code duplication.

What happens if we change the schema, so that products no longer had a seller property? What if we renamed the price property to cost? We would need to remember all of the components that handle product information, and then update each of them individually every time such a change occurred. We can avoid this by utilizing the Product interface we defined just a while ago. We’ll have the individual components' props interfaces extend that “base” type for the product data model.

import { Product } from "./path/to/mock-api-code";
...
interface ProductCardProps extends Product {
  // additional component-specific props not present on the base Product model
  ...
}
...
interface RecommendedProductProps
  extends Pick<Product, "name" | "seller" | "price"> {
  // additional component-specific props not present on the base Product model
  ...
}

Now, whenever the structure of product data in our mock back-end changes, we only have to update the Product interface to reflect that change. This update will also be reflected in any interface that extends the base Product interface, whether entirely or in part. For the RecommendedProductProps interface, we only care about a select few properties of the Product, so we’ll use the Pick utility type to extend a subset of the Product interface with just those properties.

I like to place to these interfaces and other related types in separate files, categorized more-or-less by some “domain” to which I believe they belong. As shown earlier, I usually start with a 📁 models directory inside the 📁 mock-api directory. In this 📁 models directory, I then create sub directories for each distinct domain, like so:

📁 src/ (root directory of React app)
 ├── 📁 ...
 └── 📁 mock-api/
      ├── 📁 models
      │    ├── 📁 products
      │    │    ├── 📄 product.ts
      │    │    ├── 📄 product-type.ts
      │    │    └── 📄 index.ts
      │    ├── 📁 orders
      │    ├── 📁 order-items
      │   ...
      │    └── 📄 index.ts
     ...
      ├── 📄 server.ts
      └── 📄 index.ts

If you look back at the Product interface we defined a while ago, you’ll notice it has a property, type, whose value is a ProductTypeEnum. This Typescript enum does not correspond to any model that our mock back-end cares about; the enum values become integers as far as the mock data or any data transfer objects are concerned. But the enum type will still be useful for the React components in the front-end. Because the two are so closely related in this way, I consider both the Product interface and the ProductTypeEnum to be part of the same Product domain. The enum is defined inside the 📄 product-type.ts file and the other interface is defined inside 📄 product.ts; I've purposefully grouped these two files together.

Consider a “hybrid” approach for generating realistic seed data

One of the key requirements for my UI prototype was that the sample data needed to be as realistic as possible. This involved simulating real customer scenarios, acquiring actual addresses and GPS coordinates, and so on. It’s not very common have such an extreme level of detail in a prototype, but the experience did force me to figure out creative ways to efficiently generate and handle seed data for a mock back-end.

Mirage allows you to configure initial data for a server instance by defining seed data fixtures, using the fixtures config option. Because the sheer amount of initial sample data for a realistic prototype could get very large (as was the case for my UI prototype), I like to keep the sample data fixtures in a separate file and them inject them into the createServer() function. In the example below, when the server instance is first loaded, the mock database will be seeded with the following product data:

/* product-data.ts */
import { Product } from "path/to/models";

export const products: Product[] = [
  { 
    id: 1, 
    name: "Brown Leather Jacket", 
    seller: "Acme Apparel", 
    ... 
  },
  { 
    id: 2, 
    name: "Inflatable Pool", 
    seller: "Bravo Recreation", 
    ... 
  },
  ...
  { 
    id: 10, 
    name: "Small Notepad", 
    seller: "Jones Suppliers", 
    ... 
  },
];

Now we just need to pass in the products array to the fixtures config option (N.B. — remember to use the singular form, product, when defining models, and the plural form, products, when passing in fixtures):

import { products } from "path/to/sample-data";

export function makeServer() {
  const server = createServer({
    models: {
      product: Model.extend({ ... }),
      ...
    },
    fixtures: {
      products,
    },
    ...
  });
  return server;
}

Fixtures are great if you’re willing to write out seed data by hand. For obvious reasons, this won’t be a very good use of your time in more complex scenarios. If you need to generate 1,000 or 10,000 rows of sample data, for instance, it’s better to find something that can generate the seed data for you instead.

Luckily, Mirage allows you to accomplish this pretty easily, using factories. Once again, I like to keep factories in a separate place and inject them into the server generator function. The faker.js library comes in really handy for generating all kinds of mock data — from names, to phone numbers, to addresses and more. In the examples below, a productFactory is being used to generate 2,000 Product records as initial seed data for the mock database. Custom providers in the productFactory assign product names, seller names, and other product information using mock data generated by faker modules:

/* product-factory.ts */
import { Factory } from "miragejs";
import { commerce, company } from "faker";

export const productFactory = Factory.extend({
  name(): string {
    return commerce.productName();
  },
  seller(): string {
    return company.companyName();
  },
  price(): number {
    return Math.floor(Math.random() * 300) + 20;
  },
  ...
});

import { productFactory } from "path/to/sample-data";

export function makeServer() {
  const server = createServer({
    models: { ... },
    factories: {
      product: productFactory,
    },
    seeds:(_server) {
      _server.createList("product", 2000),
    },
    ...
  });
  return server;
}

While this works fine if you need to generate reams of randomized data (great for stress-testing UI components like tables or lists), it still poses a challenge for realistic prototypes. By simply letting all of the product names, sellers, and prices be randomized, we may end up with some very strange combinations, like $30 cars sold by a “Greenwich Consulting, LLC.”, or $200 bananas sold by “Tim’s Party Supplies”, and so on. Depending on your context, you may or may not care about this level of detail. But if you do care, you may decide that, while some aspects of the seed data can be randomized, other aspects ought to remain more tightly controlled.

Let’s say that I wanted some finer control over the names and prices of products, but I was okay with randomizing the seller names and other properties of the product. Here is a “hybrid” approach that will allow me to define just the properties I want direct control over and let the factory handle the rest. I start by creating an array of sample data, but I only provide values for those properties which I want to control directly. I also expose a count of the number of items in the array.

/* product-data.ts */
import { Product } from "path/to/models";

export const products: Pick<Product, "name" | "price">[] = [
  { name: "Brown Leather Jacket", price: "54.99" },
  { name: "Inflatable Pool", price: "89.99" },
  ...
  { name: "Small Notepad", price: "3.49" },
];

export const productCount = products.length;

Next, I head over to the factory, where I keep things the same for properties being randomly generated, but change how the other properties are handled. When the productFactory iterates over the requested number of items it is asked to generate, it will track the specific index of each generated record. I can use that index to grab information for the product at that same index in my pre-defined list. If, for whatever reason, there isn’t anything at that index in my pre-defined list (this can happen if the factory is asked to generate more records than the number of records in my pre-defined list), I can have the factory fall back to a randomly-generated value instead:

import { commerce, company, datatype } from "faker";
import { products } from "./product-data";

export const productFactory = Factory.extend({
  name(index: number): string {
    return products[index]?.id || commerce.productName();
  },
  seller(): string {
    return company.companyName();
  },
  price(index: number): number {
    return products[index]?.price || Math.floor(Math.random() * 300) + 20;
  },
  ...
});

Lastly, we’ll go back to the createServer() function. Instead of generating 2,000 product records, we’ll only generate as many as we have data for. Remember how we derived productCount from the length of the products array earlier? We can now make use of that:

import { productCount, productFactory } from "path/to/mock-data";

export function makeServer() {
  const server = createServer({
    models: { ... },
    factories: {
      product: productFactory,
    },
    seeds:(_server) {
      _server.createList("product", productCount),
    },
    ...
  });
  return server;
}

The obvious drawback of this hybrid approach is that it can still be painful to generate large sets of mock data, since you’re having to define at least one or more properties by hand for each record. It’s best for scenarios where you may want a sizeable set of sample data, but you don’t necessarily need thousands of rows of said data.

I like to organize sample data fixtures and factories together in a manner similar to how I organize interfaces for data models:

📁 src/ (root directory of React app)
 ├── 📁 ...
 └── 📁 mock-api/
      ├── 📁 factories
      │    ├── 📁 products
      │    │    ├── 📄 product-data.ts
      │    │    ├── 📄 product-factory.ts
      │    │    └── 📄 index.ts
      │    ├── 📁 orders
      │    ├── 📁 order-items
      │   ...
      │    └── 📄 index.ts
     ...
      ├── 📄 server.ts
      └── 📄 index.ts

Split up and aggregate route handlers

Similar to the models, seed data fixtures, and factories, I like to keep custom route handlers in separate files and inject them into the server instance generator function.

📁 src/ (root directory of React app)
 ├── 📁 ...
 └── 📁 mock-api/
      ├── 📁 routes
      │    ├── 📁 user-favorites
      │    │    ├── 📄 get-favorites-by-user.ts
      │    │    ├── 📄 add-favorite-product.ts
      │    │    ├── 📄 remove-favorite-product.ts
      │    │    └── 📄 index.ts
      │    ├── 📁 orders
      │    ├── 📁 order-items
      │   ...
      │    └── 📄 index.ts
     ...
      ├── 📄 server.ts
      └── 📄 index.ts

Each custom route handler gets its own separate file. For instance, I’ve defined a custom route handler that allows a user to designate a product as one of their favorites. The implementation of this route handler is in the 📄 add-favorite-product.ts file.

The manner of organization here may invite some questions: do route handlers for adding/removing a product to a user’s favorites belong in the “products” domain or in the “user-favorites” domain? The current organization seems to suggest the latter. In this hypothetical scenario, when designating products as a user favorite, we’d most likely call a PUT endpoint at the route .../api/user-favorites/some-product-id. When removing a product from the user favorite list, we would call a DELETE endpoint at the same route. As this topic is beyond the scope of this article, I won't venture too far into the weeds here.

Certain custom route handlers (e.g. a POST or PUT endpoint that modifies a user’s account info) may require specific request payloads. I like to define Typescript interfaces for all data transfer objects, whether they are the request payloads provided to route handlers or the response objects returned. I typically keep these interfaces alongside the route handlers to which they are related. These interfaces can be exposed to client app components that call the related API endpoints, greatly increasing reliability with stricter type controls.

To ensure that my custom route handlers will get called when API calls are made, I must first ensure the routes are being registered with the server instance. Let’s take a look inside the 📄 index.ts file in the 📁 user-favorites directory:

/* routes/user-favorites/index.ts */
import { Server } from "miragejs";
import { getFavoritesByUser } from "./get-favorites-by-user";
import { addFavoriteProduct } from "./add-favorite-product";
import { removeFavoriteProduct } from "./remove-favorite-product";

export function registerUserFavoritesRoutes(context: Server) {
  return [
    context.get(
      "/user-favorites/user/:userId/", 
      getFavoritesByUser, 
      { timing: ... }
    ),
    context.post(
      "/user-favorites/:productId", 
      getFavoritesByUser
    ),
    context.delete(
      "/user-favorites/:productId", 
      getFavoritesByUser
    ),
  ];
}

I register each individual route handler with the server context, which is passed in as the lone parameter of the function. All that’s left to do is to give this function to createServer() so that the server registers these routes upon instantiation. We’ll need to pass a value for the context parameter. To do this, we simply pass in a reference to the server instance — this:

import { registerUserFavoritesRoutes } from "../routes";

export function makeServer() {
  const server = createServer({
    models: { ... },
    factories: { ... },
    seeds: { ... },
    routes: {
      registerUserFavoritesRoutes(this);
    },
    ...
  });
  return server;
}

Create API client functions for UI components

I like to decouple the mock back-end from the client app as much as possible to keep the front-end lean and efficient. I define API “client functions” that serve as convenience wrappers around the actual fetch (or axios, or whatever) call, like the addUserFavorite() function shown below. These functions provide simple APIs for components to use. All of the functionality for actually making the API call and returning the results is contained within the functions themselves.

async function addUserFavorite(
  userId: string, 
  productId: string
): Promise<UserFavoriteDTO> {
  try {
    const response = await fetch(`/mock-api/user-favorites/${productId}`, {
      method: "PUT",
      cache: "no-cache",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        userId,
      });

      if (response.ok) {
        return response.json() as Promise<UserFavoriteDTO>;
      }
      throw new Error(...);
    });
  } catch (reason) {
    ... // Handle other errors
  }
}

I aggregate all the client functions for a particular domain inside a single object, and then expose this object to the front-end:

const userFavoritesClient = {
  list: getUserFavorites,
  add: addUserFavorite,
  remove: removeUserFavorite,
};
export default userFavoritesClient;

Let’s say that users can add products to their list of favorites by clicking some button next to a product’s information card. The component responsible for that interaction needs to be able to call the API endpoint to designate a new “favorite product”. All we have to do now is call the function we just defined. Any information necessary to perform the request (information which could determine the actual route or which could comprise a request payload) can be passed in as parameter(s):

import { userFavoritesClient } from "./mock-api";

function SomeComponent(props: SomeComponentProps) {
  const { productId, ... } = props;
  const { userId, ... } = useContext(...);
  ...
  async function addFavorite() {
    try {
      await userFavoritesClient.add(userId, productId);
      ...
    } catch (reason) {
      ...
    }
  }
  ...
  return (
    ...
      <Button onClick={addFavorite}>
        Add to Favorites
      </Button>
    ...
  );
}

The component doesn’t need to concern itself with which specific route needs to be called or what API base URL ought to be used. The developer doesn’t have to worry about writing tedious fetch calls every time, properly serializing request payloads, or deserializing responses. The code is clean and streamlined.

My way of organizing the client functions is pretty rudimentary: I put all API client functions related to a particular domain in one file and expose one “client” object from each file, as shown earlier. I place all of these files in one 📁 clients directory:

📁 src/ (root directory of React app)
 ├── 📁 ...
 └── 📁 mock-api/
      ├── 📁 clients
      │    ├── 📄 products-client.ts
      │    ├── 📄 orders-client.ts
      │    ├── 📄 user-favorites-client.ts
      │   ...
      │    └── 📄 index.ts
     ...
      ├── 📄 server.ts
      └── 📄 index.ts

Set up passthroughs and a unique namespace for mock routes

There are several reasons why you may want to have a mock back-end coexist with an actual back-end, even if temporarily and under specific circumstances. During development, you may want to have live data flowing into some parts of an application while other parts, especially those still under construction, remain connected to a mock back-end with sample data. You might be concerned with mocking up only a portion of the back-end that doesn’t exist yet, while the remainder of the application remains wired up.

We did eventually start building out the actual back-end. The sample data, when the application was still a UI prototype, was of very high quality and greatly facilitated demos and discussions with customers. We found that setting up the same amount of realistic data in the actual back-end would take days, maybe weeks. For this and various other reasons, we decided to keep a “demo” mode for the application:

When the demo mode was disabled, the application would display live data. The application’s API calls would hit the actual backend and queries would be performed on the actual database.
Enabling the demo mode would result in the sample data being displayed. API calls would be intercepted by Mirage and the mock database instance would instead be the target for all queries performed.

By default, Mirage intercepts all outgoing HTTP requests in a manner similar to monkey-patching, disallowing communication with web APIs at the same time. To allow some requests to pass through, you must explicitly declare passthrough routes. This is done in the routes config property which we used earlier to inject custom route handlers. I tend to put this all the way towards the end:

import { injectUserFavoritesRoutes } from "../routes";

export function makeServer() {
  const server = createServer({
    models: { ... },
    factories: { ... },
    seeds: { ... },
    routes: {
      ...
      this.passthrough((request) => {
        // Custom comparator function
        // Return true if Mirage should allow the request
        // to pass through, or false if it should be
        // intercepted
        return request.url.includes("api/v1");
      });
    },
    ...
  });
  return server;
}

In the above example, Mirage will not intercept any HTTP requests that include api/v1 as part of the request URL. You can also pass in fully-qualified domain names if any API requests will go to some external domain, and you can provide as many passthrough route declarations as you want:

const server = createServer({
  ...
  routes: {
    ...
    this.passthrough("https://localhost:9001/api/**");
    this.passthrough("https://external-domain-one.com/api/**");
    this.passthrough("https://api.external-domain-two.net/v1/**");
    ...
  },
  ...
});

I also like to include one additional thing — a custom namespace for the mock API routes:

const server = createServer({
  ...
  routes: {
    this.namespace = "/mock-api";
    ...
    this.passthrough(...);
    ...
  },
  ...
});

In the front-end, calls to the mock back-end will now include mock-api as part of the route, to distinguish them from calls to the actual back-end (which we will allow to pass through).

Closing thoughts

The recommendations herein likely reflect some of my personal biases. They are not meant to be rules or exhaustive guidelines by any means. There’s so much more to Mirage; I've only scratched the proverbial surface, but I’ve learned quite a few things along the way. I share these tips in the hopes that, whether you’re new to Mirage or already quite familiar with it, they might come in handy for you as well.

There are even more tips and useful methodologies I'd love to share with you, but I fear this article would become far too long if I tried to cram them all in here. I have plans for an npm package with some useful functions and hooks I've built that make the process of generating realistic mock data less of a hassle. I'll have more details on that in the near future.

Is there anything in here you particularly liked? Do you have concerns or suggestions for improvement, or have you spotted any errata? Have you worked with Mirage before and have some ideas or approaches you’ve found useful which were not mentioned here? Please leave a comment!

Thanks for reading!

React Hooks Explained: useImperativeHandle

Anik — Tue, 13 Apr 2021 02:57:42 +0000

A Note From the Author
Intro
Unidirectional Data Flow
Adding Imperative Logic
Imperative Handling and Function Components
Use It Wisely
Additional Reading

A Note From the Author

I've seen some decent explanations here and there on how to use React's useImperativeHandle hook — Kent C. Dodds' React course has a great short exercise on how to properly use this hook. But I still feel like there's room for more conversation around exactly when to use this hook, because it's the sort of thing you should be doing sparingly and only in certain situations where it's the most logical (or only remaining) choice.

This is my first post here on DEV (✨🥳🎉) and I intend for this to be the first in a series of short articles centered around React and Typescript. I started working with React about four years ago and I'm excited to share with you some of what I've learned since then. If you notice any errors, please do let me know!

Intro

With rare exception, data flow in React apps is unidirectional. Components comprise a hierarchy of parent and child nodes. Child nodes are privy to information and can call functions that have been passed down to them from parent nodes, via a declarative “props” API. Parent nodes, on the other hand, do not have access to (and are not affected by) the internal state of child nodes. Parent nodes also generally do not call functions declared within child components.

Callback functions usually suffice when closer coordination between parent and child nodes is necessary. More intricate situations involving multiple moving parts and dense component hierarchy may call for things like Redux or the built-in Context API. Even so, parent nodes are usually not given direct control over child nodes.

But what about those very rare situations where callbacks, contexts, and whatnot are simply not enough — where the cleanest, most flexible, or perhaps the only option left is to let the parent directly control the child and imperatively dictate what the latter should do? Let’s see how such a situation might arise, and what we can do about it.

Unidirectional Data Flow

Let’s say you’ve been tasked with building a “comments feed” component that will be used in a number of different places throughout several applications. The exact use cases will vary; all you have to work with are the following acceptance criteria:

Criterion #1: The comments feed should accept a list of existing comments (an array) as one of its props, and should display them.
Criterion #2: The comments feed should have a form at the bottom which allows the user to add new comments. This form should consist of two fields: one for the user’s name, and one for the new comment itself. At the bottom of the form, there should be a “Submit” button that lets the user request that the new comment be added.
Criterion #3: When the user clicks the button, the comments feed should send up the information from the new comment form (user’s name and new comment) to the parent component that mounted it. It is that parent component’s responsibility to process the request, update the list of existing comments, and give the updated comment list to the comments feed to display.

Here’s what a very basic implementation of the comments feed might look like (we’ll name this component Comments):



const Comments = (props: {
  comments: [];
  onSubmitComment: (name: string, newComment: string) => void;
}) => {
  // State management for form
  const [values, setValues] = useState({
    name: "",
    newComment: "",
  });

  // Handle changes to form fields
  function handleChange (event) {
    setValues((values) => {
      ...values,
      [event.target.name]: event.target.value,
    });
  }

  // Function that renders content of each comment
  function renderComment (comment) { ... }

  // Submit comment
  function handleSubmit () {
    const { name, newComment } = values;
    props.onSubmitComment(name, newComment);
  }

  return (
    <>
      <ul>
        {props.comments.map(renderComment)}
      </ul>

      <h4>Add a comment</h4>
      <form>
        <label for="name">Your Name</label>
        <input
          name="name"
          type="text"
          value={values.name}
          onChange={handleChange}
        />

        <label for="newComment">Your Comment</label>
        <textarea
          name="newComment"
          rows={4}
          value={values.newComment}
          onChange={handleChange}
        />
      </form>

      <button onClick={handleSubmit}>Submit</button>
    </>
  );
};

This component expects to be given two props. The first prop, comments, supplies the list of comments to be displayed. The comments are rendered as list-items within an unordered list. This fulfills criterion #1.

The form allows the user to type in their name and the new comment. There’s a “Submit” button at the bottom of the form that can be clicked to submit the new comment. This fulfills criterion #2.

The second prop supplied to this component is a callback function, onSubmitComment. This callback function expects two parameters to be passed in: the name of the person submitting the comment, and the comment itself. When the Submit button is clicked, the handleSubmit function is executed. Inside it, the onSubmitComment callback function is executed and the values that the user typed into the form are passed in. This is how the Comments component will “send up” to its immediate parent the new comment that is to be saved. This fulfills the third and final acceptance criterion.

Now let’s see how a “parent” component would implement the Comments component:



const Article = () => {
  // State management
  const [comments, setComments] = useState([]);

  // Load comments when component mounts
  async function loadComments () {
    const existingComments = await fetch(...) // API request to get comments
    setComments(existingComments); // Store comments in state
  }
  useEffect(() => {
    loadComments();
  }, []); 

  // Event handlers
  async function addComment (name: string, newComment: string) {
    // API request to persist new comment...
    // Optimistic update of comments list...
    ...
  }

  return (
    <div>
      <article>
        ...
      </article>
      ...
      <Comments
        comments={comments}
        onSubmitComment={addComment}
      />
    </div>
  );
};

As shown above, the parent component, once mounted, loads the initial set of comments. The comments list, stored in the comments state variable, is passed down to the Comments component, which is mounted as a child of this parent component. The addComment() function is assigned to the onSubmitComment prop’s value. When the user clicks the “Submit” button, the Comments component is effectively calling the parent component’s addComment() function, by way of the onSubmitComment prop.

This is a very basic example of coordinating parent and child node behavior without violating unidirectional flow. The values in the new comment form, and the submit button, and any interactions thereof, are none of the parent component’s concern. The parent doesn’t directly “reach in” and grab information stored inside the child component. Instead, the parent component gives the child a callback function and expects the child to call said function whenever a new comment is to be added. The parent cannot call the handleSubmit() function declared inside the Comments component.

Adding Imperative Logic

If you’ve worked extensively with forms in React apps, you may be familiar with how input elements expose functions like blur, focus, and select which can be used to programmatically blur or focus a field, or to select all text inside a field, respectively. Normally, when the user clicks inside a field, that field is focused, and when the user moves to another field or clicks outside, that previous field is blurred. But sometimes, it’s necessary to do these things without waiting for user input.

When the user first loads a form inside a page or a dialog, it can be beneficial to the user’s experience to immediately place keyboard focus on the first field in the form (or whichever field the user is expected to start typing in first). Doing so saves the user some time and motor interaction cost otherwise needed to move their mouse cursor to the field and click on it.

There are other situations where you may want to do something like this. If the user attempts to submit a form, but there was an error in one of the fields, it would be really nice if the application automatically focused on the field with the error (and made sure that the field in question had been scrolled into view).

Let’s say that we are given an additional acceptance criterion for our new Comments component:

Acceptance Criterion 4: When the comments feed is mounted and made visible to the user, the “Your Name” field should immediately be given keyboard focus.

Revisiting the Comments component again, we see that the new comments form currently looks like this:



...
  <form>
    <label for="name">Your Name</label>
    <input
      name="name"
      type="text"
      value={values.name}
      onChange={handleChange}
    />

    <label for="newComment">Your Comment</label>
    <textarea
      name="newComment"
      rows={4}
      value={values.newComment}
      onChange={handleChange}
    />
  </form>
...

We want the first input, the “Your Name” field, to be immediately focused as soon as the Comments component mounts. It’s not like we can change the input’s value (or some other prop) and expect the input to auto-focus again. The parent (in this case, the Comments component) node simply needs a way to directly (imperatively) call the focus function on behalf of the child (the input).

This is one of the simplest examples of imperative logic in action. We've finally encountered a situation where it's actually called for!

In order to get access to that function, though, we need a way to reference the specific input element in question. In React, we do this by using a ref (we’ll call it nameInputRef):



const Comments = ...
...
  const nameInputRef = useRef();
  ...
  return (
    ...
      <form>
        <label for="name">Your Name</label>
        <input
          name="name"
          type="text"
          value={values.name}
          onChange={handleChange}
          ref={nameInputRef}
        />
        ...
      </form>
    ...
  );
};

The focus() function can now be accessed via nameInputRef.current. With the help of a useEffect hook, we can call this function after the Comments component is first mounted and rendered.



...
  const nameInputRef = useRef();
  useEffect(() => {
    if (nameInputRef.current) {
      nameInputRef.current.focus();
    }
  }, []);
...

Imperative Handling and Function Components

Let’s say our Comments component is now being used in numerous applications. On some pages, it’s at the bottom. On other pages, it’s placed off to the side. It’s also inside a few dialogs and tooltips. In all these cases, it is immediately rendered with the “Your Name” field auto-focused. However, as its usage increases, developers start to find themselves in situations where the “auto-focus first field on initial mount” behavior is insufficient.

One day, a developer is tasked with implementing your comments feed in a slightly different manner. At the bottom of the page, there’s a set of collapsible accordion tabs, each with different content within. One of these accordion tabs contains the comments feed. To view the comments feed, the user must expand the accordion tab by clicking “View Comments”, like so:

The developer working on this was told that whenever the comments section is expanded, the “Your Name” field must always be initially auto-focused. They achieved this by mounting the comments feed only when the accordion tab is expanded, and unmounting it when it is collapsed. This way, expanding the accordion tab always results in the comments feed being freshly re-mounted. Whenever this happens, the useEffect side effect is executed, and the “Your Name” field is once again auto-focused.

The project manager and UX lead, however, were not satisfied with this workaround. You see, if a user begins typing a comment and then collapses the comments section, whatever they painstakingly typed in will be instantly annihilated when the comments feed is unmounted. After expanding the comments section again, they will find to their dismay that everything they wrote is now lost to the sands of time.

There are some other ways of getting around this issue: you could temporarily store (in local storage, for instance) whatever the user typed in. These stored values could then be passed in to the comments feed as “initial values” when the component is re-mounted.

But for the sake of our discussion, what if we could avoid adding more props and making significant changes to the Comments component by doing something similar to what we did earlier with the input field? What if the Comments component contained a function to focus on the “Your Name” field, and exposed this function to any parent implementing it, just like the focus() function exposed by the input element? This function could then be imperatively called by any parent, whenever necessary.

Step 1: Define a function in the child component

Let’s first define said function inside the Comments component. We’ll call it focusOnForm():



const Comments = ...
...
  const nameInputRef = useRef();

  function focusOnForm () {
    if (nameInputRef.current) {
      nameInputRef.current.focus();
    }
  }
  useEffect(focusOnForm, []);
...

All we’ve really done so far is move all the logic previously defined inside the useEffect hook to its own separate function. We are now calling that function inside the useEffect.

Remember how we needed to reference the specific input element by way of a ref in order to access its focus() function? We’ll need to do something similar in order to allow the parent component to access the focusOnForm() function inside the Comments component.

Step 2: Define a ref in the parent component and pass it to the child

Let’s go back up to the parent now. First, we’ll define a new ref, called commentsFeedRef. Then, we’ll assign the ref to the Comments component, via the ref prop, just as we did with the input element:



const Article = () => {
  ...
  const commentsFeedRef = useRef();
  ...
  return (
    ...
    <Comments
      comments={comments}
      onSubmitComment={addComment}
      ref={commentsFeedRef}
    />
  );
};

If this was 2018, and our Comments component was a class component, this would be perfectly fine and we would be well on our way. But this is the f u t u r e, man — the Comments component is a function component. And unlike class components, function components do not have an associated component instance when they are mounted. In other words, there is no way to access some “instance” of a function component via a default ref property. There’s a little more work we must do first.

Simply adding a ref property to the existing props on the Comments component will not work either, by the way, so the following approach is also incorrect:



const Comments = (props: {
  comments: [];
  onSubmitComment: (name: string, newComment: string) => void;
  ref,
}) => ...

Instead, we have to use the forwardRef feature provided by React in order to pass a ref to our function component.

Step 3: Use forwardRef to allow a ref to be passed to the child

There are a few different ways of doing this but here’s the approach I usually prefer, as it’s pretty clean and easy to follow. We first need to define the component as a named function instead of an anonymous function assigned to a constant:



function Comments (
  props: {
    comments: [];
    onSubmitComment: (name: string, newComment: string) => void;
  }
) {
  ...
  function focusOnForm () { ... }
  ...
}

Let’s say we were previously exporting this component as a module-level default export:



export default Comments;

We now need to first pass the Comments component to the forwardRef higher-order component, and then export the result:



export default React.forwardRef(Comments);

Next, we’ll add the ref property to the Comments component. Notice, however, that the ref property is kept separate from the main component props:



function Comments (
  props: {
    comments: [];
    onSubmitComment: (name: string, newComment: string) => void;
  },
  ref
) {
  ...
  function focusOnForm () { ... }
  ...
}

The parent component can now pass a ref to the Comments component, and use it to call the focusOnForm() function. When we call it, we’ll probably do something like this:



...
commentsFeedRef.current.focusOnForm();
...

But this still won't work. What gives?

Well, the ref's current property doesn't actually have the focusOnForm function in it yet. We first need to define exactly what gets exposed via the current property.

Step 4: Expose function(s) via passed ref, with useImperativeHandle

We’ll accomplish that with useImperativeHandle:



function Comments (
  props: {
    comments: [];
    onSubmitComment: (name: string, newComment: string) => void;
  },
  ref
) {
  ...
  function focusOnForm () { ... }
  useImperativeHandle(
    // Parameter 1: the ref that is exposed to the parent
    ref,
    // Parameter 2: a function that returns the value of the ref's current property,
    // an object containing the things we're trying to expose (in this case, just
    // one function)
    () => {
      return {
        focusOnForm: focusOnForm,
      }
    }
  );
  ...
}

We’re passing two parameters into useImperativeHandle. The first parameter simply indicates the ref that is being exposed to the parent.

In the second parameter, we pass a function that returns an object containing the various functions and properties we are trying to expose to the parent. useImperativeHandle will return this object when the parent accesses the current property of the ref passed in as the first parameter.

We can simplify it, like so:



useImperativeHandle(
  ref,
  () => ({
    focusOnForm,
  })
);

There’s actually a third, optional parameter. You can pass in an array of dependencies, and useImperativeHandle will recalculate what is to be returned when any of those dependencies change. This can be useful if anything you’re returning is being influenced by the child component’s state; for instance:



const [someValue, setSomeValue] = useState<number>(...);
...
useImperativeHandle(
  ref,
  () => ({
    someFunction: (value) => value * someValue,
  }),
  [someValue]
);

For now, though, we won’t be needing that.

Now, when the Comments component is passed a ref, it will immediately assign an object to the value of the ref’s current property. For now, this object only contains the focusOnForm() function.

Step 5: Call function(s) exposed by child, via the ref passed to the child

Going back to the parent component, we can see how the focusOnForm() function, defined inside the child component, can now be called inside the parent:



const Article = () => {
  ...
  const commentsFeedRef = useRef();
  ...
  function focusOnNewCommentForm () {
    if (commentsFeedRef.current) {
      commentsFeedRef.current.focusOnForm();
    }
  }
  ...
  return (
    ...
    <Comments
      comments={comments}
      onSubmitComment={addComment}
      ref={commentsFeedRef}
    />
  );
};

With this, the developer can now easily call focusOnForm() whenever necessary, without having to unmount and remount the Comments component. The showComments variable shown below controls the expanded / collapsed state of the comments section. A useEffect hook watches for changes in its value. Whenever its value changes to true, we'll call focusOnForm().



const Article = () => {
  ...
  const [showComments, setShowComments] = useState(false);
  useEffect(() => {
    if (showComments && commentsFeedRef.current) {
      commentsFeedRef.current.focusOnForm();
    }
  }, [showComments]);
  ...
  return (
    ...
    <Accordion ...>
      <Accordion.Tab show={showComments}>
        <Comments
          comments={comments}
          onSubmitComment={addComment}
          ref={commentsFeedRef}
        />
      </Accordion.Tab />
    </Accordion>
  );
};

Great! Now the “Your Name” field in the new comment form will always be re-focused whenever the comments feed is displayed again, even though the Comments component has not been unmounted and re-mounted.

Use It Wisely

At the end of the day, useImperativeHandle isn’t used very often, and with good reason – it’s an escape hatch, a fire escape, a method of absolute last resort when other options have failed or are simply not viable.

One of the rare spots where I’ve encountered useImperativeHandle in the wild is when there's some kind of scrollable area and button to let the user scroll all the way back up to the top. It’s simple enough to just get the element in question (either via ref, or with a document.querySelector query), and call scrollTop = 0. But you don’t want developers to have to write this logic every time they implement the component in question – the component should expose some property that can be passed a value which triggers the effect, right?

But you'll quickly find that passing in a value doesn’t make much sense for an imperative action. What would you pass in? A boolean variable (onRequestScrollToTop) with the value true? Does this variable then get set back to false? Does the parent set it back to false with setTimeout and a short delay? Or is there a callback function (onScrollToTop) which is executed after the scroll-to-top is complete, at which time the variable in question is set to false? All of these sound equally awful and unnecessary.

It’s peculiar and rare situations like these where useImperativeHandle actually shines and should actually be considered. Conversely, if you don’t find yourself asking these types of questions, you can probably accomplish what you’re trying to do without using useImperativeHandle.

Here’s another thing to think about: when you’re creating components for others and publishing them as open-source tools, it’s impossible to predict in advance all the ways in which they are going to be used. There are clear advantages to constructing our components in a way that maximizes their flexibility. That comments feed, for instance: there’s nothing saying it has to be used in an accordion. Perhaps, in some rare cases, adding useImperativeHandle could allow developers to use specific features in specific situations without us being forced to drastically alter the original component every single time a new, unique situation arises.