Doordash Building Isomorphic JavaScript Libraries

Isomorphic JavaScript libraries are helpful when running code both client-side and server-side. Building them comes with many challenges that include adding the right dependencies, creating a function declaration identical in both environments, and testing. The successful creation or abandonment of any isomorphic library includes constant obstacle solving or final decision on when the complexities of the build outweigh later efficiencies.

Online delivery service DoorDash has found that its code logic works well across multiple environments through isomorphics. The web platform team writes code in several JavaScript environments, including React and Node.js. To further blurr the lines, several pages are also undergoing a migration from client-side to server-side rendering as discussed in the blog post written by Software Engineer Nick Fahrenkrog.

The tradeoff with isomorphic libraries is how complex they are to build vs their efficiency. The best way to illustrate these challenges and techniques employed at scale is to follow along as Fahrenkrog builds a fictitious isomorphic library.

Functional Requirements

The following example is written in TypeScript.

What makes building an isomorphic library challenging? Relying on APIs native in one environment but not in another, ie. “fetch” or “document.cookies”. Other challenges include:

• Working with dependencies that aren’t isomorphic.
• Functions that behave differently client-side vs server-side.
• Exposing parameters that aren’t needed in all environments.

As to include as many challenges in DoorDash’s example, the fictitious library build will export a function to check if a coffee order is ready via a network request and send a unique id.

The scope:

— Export an async function named “isCoffeeOrderReady” which optionally takes “deviceId” as a parameter and returns a Boolean.

• Send an http POST request with the request body “{deviceID:<deviceID>}” to a hard-coded endpoint.
• Run in Node.js or browser.
• Browser will read “deviceID” directly from cookies.
• Use keep-alive connections.

With the details scoped, it’s time to dive into the five primary challenges with implementing isomorphics, and how to overcome them.

Challenge 1: Choosing the Right Dependencies

For illustration purposes. This is Node <= 16 and it doesn’t use any experimental flags. Node 18 has native fetch support.

Browsers can support fetch but here’s a decision to make: an isomorphic library or a Node.js library? Choose the Node.js library and it might be scrutinized for its impact on the bundle size in the browser. Choose the isomorphic and it needs to fulfill every environment’s requirements for dependences…

DoorDash chose isomorphic-fetch — a combination of node-fetch in Node.js and GitHub fetch polypill in browsers. The code below is an example of the fetch request.

The next divergence is handling “deviceId”. “deviceId” is a parameter sent via the fetch request in the Node.js environment but in the browser, it’s read directly from a cookie.

The window should always be defined in the browser, not globally in Node.js. So document.cookie is defined in the window. The code now looks like the image below.

👁 Image

This isn’t the only way of detecting whether code is on the server or client though it’s a popular way. More information can be found here.

This new code file added another challenge.

Challenge 2: Designing a Unified API Between Environments

The “deviceId” parameter is a required argument in Node.js but not in the browser. Before moving any further, the function declaration must be identical in both environments. Two possible solutions are:

Write the API as shown, requiring “deviceId”. Caution this action could be misleading to adopters because that value must be passed in the browser even though it will be ignored.

Make “deviceId” optional. This allows the function invocation in the browser without the argument and in Node.js with the argument. The caution here is that it can also be called in Node.js without the argument. TypeScript will not prevent misuse of the API.

The second approach is the better choice but it’s not fail-proof.

Challenge 3: Ensuring Dependencies Only Affect Intended Environments

The “document.cookie” code change introduced another issue. “Cookie”, installed in Node.js, isn’t used in the code path. It’s better to have unnecessary dependences in Node.js than the browser but best to avoid them altogether when possible and aim for minimal bundle size.

There’s a two-step process for this: separate the code files, one for Node.js and one for browser, then use a bundler (such as webpack) that supports tree shaking.

The importance of choosing the right dependencies. node-fetch implements a different spec than the native browser fetch and one of the areas of divergence are the keep-alive connections. Add the following flag to use a keep-alive connection in browser fetch:

fetch(url, { ..., keepalive: true })

In node-fetch create “http” and/or “https” http.Agent instances and pass that as an agent argument to the fetch request as shown here:

👁 Image

In Node.js environments, keep-alive connections can’t be set up correctly with isomorphic fetch because isomorphic-fetch utilizes node-fetch internally but doesn’t expose the agent options. In order to set up the keep-alive connections correctly, the native fetch and node-fetch libraries will both need to be used.

This can be done by splitting the entry points by environment-specific code paths.

Separate entry points are acceptable but only one TypeScript types declaration file can be used in keeping with goal of an isomorphic library, to expose the same API regardless of the environment.

Here’s a list of other isomorphic JavaScript libraries using this pattern for purposes of isomorphic fetch.

• isomorphic-fetch
• isomorphic-unfetch
• ky-universal
• fetch-ponyfill

The final code paths look like this, as documented in the index.ts files.

👁 Image

…And in the browser.ts file:

👁 Image

And with that, the library’s functional requirements are complete. The full benefit of isomorphism isn’t showcased as there is little shared code but in larger projects there is more opportunity for shared code. It’s also important to be certain that everything exported has the exact same API because only one list of type declaration files is published.

Challenge 4: Testing Every Environment

Testing each environment is very much the vegetables of coding: it’s good for you even though you don’t want to do it. One key factor to consider when testing isomorphic libraries is that most test will need to be written twice to make sure identical functionality exists in both environments. Since isomorphism couples logic across all environments, changes in one environment needs testing in another.

Challenge 5: Observability and Metrics

The infrastructure for observability looks very different in both environments. Node.js may be extended to capture latency, error rate, and log warnings and errors with context to help trace across microservices while the browser might only expand to capture errors. The same problem-solving patterns detailed earlier can resolve these differences.

Final Thoughts

Several challenges arose throughout the build of the fictitious library but they were all solvable. The tradeoffs vs the benefits were considered, and solutions were met. This is one example of one approach and a quick google search shows endless information and depth on this isomorphism.