Forem: Graham Marlow

Better React Micro Frontends w/ Nx

Graham Marlow — Tue, 14 Sep 2021 19:09:35 +0000

One of the first articles we covered in tech book club was Micro Frontends, an approach to scaling frontend development across many independent and autonomous teams.

Although the content of the article is well-articulated, the accompanying example is lacking. It hacks create-react-app with an extra package to enable Webpack builds and offers no mechanism to run all of the micro frontend applications in tandem. The example is easy to follow, but inspires no confidence for a real-world scenario.

After experimenting with different tools and approaches, I think I've constructed a better scaffold for micro frontends that improves the overall developer experience. This article walks you through that approach.

You can find the complete example here.

Monorepos with Nx

One of the major disadvantages to micro frontends is complexity. Rather than maintaining all of your application code in one place, that code is now spread across multiple applications and managed by separate teams. This can make collaboration on shared assets difficult and tedious.

Keeping each micro frontend within the same repository (monorepo) is one easy way to help manage this complexity. Google famously uses this technique to manage its billion-line codebase, relying on automation and tools to manage the trade-offs.

Rather than using create-react-app to bootstrap micro frontends, turn instead to Nx. Nx is a build framework that offers tools to manage a multi-application monorepo, a perfect fit for micro frontends.

Here are a few ways Nx helps manage micro frontends:

Script orchestration: run servers/builds for multiple micro frontends concurrently with a single command.
Share common components and code libraries conveniently without introducing lots of Webpack overhead.
Manage consistent dependency versions.
Run builds and tests for affected changes across micro frontends based on dependency graphs.

Nx is certainly not the only tool that supports monorepos, but I’ve found it to be a great fit for micro frontends thanks to its built-in React support and batteries-included functionality. Lerna is noteworthy alternative that offers less built-in functionality at the advantage of flexibility.

Detailed example

Nx requires only a few configuration changes to support micro frontends and you won’t need the help of an ejection tool like react-app-rewired.

Create a new Nx workspace with two React applications (one container, one micro frontend).
Extend Nx’s default React Webpack configuration to disable chunking and generate an asset manifest.
Implement conventional micro frontend components as described in the Thoughtworks article.
Tie it all together with a single npm start script.

1. Create the Nx workspace

Begin by creating a new Nx workspace:

npx create-nx-workspace@latest micronx

? What to create in the new workspace...
> empty
Use Nx Cloud?
> No

Navigate into the new micronx directory and create two React applications, one container and one micro frontend. It’s important to select styled-components (or another CSS-in-JS solution) so that your component CSS is included in the micro frontend’s JS bundle.

cd ./micronx
npm install --also=dev @nrwl/react

# Container application
nx g @nrwl/react:app container
> styled-components
> No

# Micro frontend
nx g @nrwl/react:app dashboard
> No

So far you've created a monorepo with two separate React applications: container and dashboard. Either React application can be served independently via its respective nx run <app>:serve script, but there's nothing yet in place to have them work together.

The next step sprinkles in some configuration changes that allow you to dynamically load the dashboard application as a micro frontend.

2. Modify micro frontend Webpack configuration

Nx stores most of its relevant configuration in the workspace.json file stored at the project's root.

You need to modify workspace.json to point the micro frontend’s Webpack configuration to a new file, webpack.config.js. This new file contains the configuration updates necessary to support dynamically loading the micro frontend.

Note that you don’t need to do this for the container, since the container is not a micro frontend.

// workspace.json
"projects": {
  "dashboard": {
    "targets": {
      "build": {
        // ...
        "webpackConfig": "webpack.config.js"
      }
    }
  }
}

Now you need to create that file, webpack.config.js, at the root directory of the project.

This modified Webpack configuration extends the default code from @nrwl/react to avoid losing any functionality. Following the Thoughtworks example, two modifications are needed to support conventional micro frontends:

Disable chunking so the container application loads one bundle per micro frontend.
Add WebpackManifestPlugin to map the generated JS output to an easy import path (taken from react-scripts webpack configuration).

npm install --also=dev webpack-manifest-plugin

// webpack.config.js
const reactWebpackConfig = require('@nrwl/react/plugins/webpack')
const { WebpackManifestPlugin } = require('webpack-manifest-plugin')

function getWebpackConfig(config) {
  config = reactWebpackConfig(config)

  // Disable chunking
  config.optimization = {
    ...config.optimization,
    runtimeChunk: false,
    splitChunks: {
      chunks(chunk) {
        return false
      },
    },
  }

  // Enable asset-manifest
  config.plugins.push(
    new WebpackManifestPlugin({
      fileName: 'asset-manifest.json',
      publicPath: '/',
      generate: (seed, files, entrypoints) => {
        const manifestFiles = files.reduce((manifest, file) => {
          manifest[file.name] = file.path
          return manifest
        }, seed)
        const entrypointFiles = entrypoints.main.filter(
          fileName => !fileName.endsWith('.map'),
        )

        return {
          files: manifestFiles,
          entrypoints: entrypointFiles,
        }
      },
    }),
  )

  return config
}

module.exports = getWebpackConfig

Run nx run dashboard:serve and visit http://localhost:4200/asset-manifest.json. Note that the dashboard application now only has one entry point: main.js.

{
  "files": {
    "main.js": "/main.js",
    "main.js.map": "/main.js.map",
    "polyfills.js": "/polyfills.js",
    "polyfills.js.map": "/polyfills.js.map",
    "assets/.gitkeep": "/assets/.gitkeep",
    "favicon.ico": "/favicon.ico",
    "index.html": "/index.html"
  },
  "entrypoints": ["main.js"]
}

3. Add in micro frontend components

With Nx configured properly, the next step is to follow Thoughtworks example and introduce all of the micro frontend functionality.

The following links don't deviate from the article, but are included for completeness.

4. Tie everything together

The last step is to serve the micro frontend and container together. Add concurrently and modify your start script to serve the dashboard on a specific port.

"start": "concurrently \"nx run container:serve\" \"nx run dashboard:serve --port=3001\""

Run npm start and you've got micro frontends.

Working with Nx

Serving micro frontends

Nx doesn't have out-of-the-box functionality for serving multiple applications simultaneously, which is why I resorted to concurrently in the above example. That said, running individual micro frontends is made easy with the Nx CLI.

Develop micro frontends independently via nx run <project>:serve.
See how they fit into the whole application via npm start.

Generators

Nx ships with a handful of generators that help scaffold your application. In particular, the library generator makes it really easy to share React components:

nx g lib common

This creates a new React library in your project's libs/ directory with a bunch of pre-configured build settings. Included is a convenient TypeScript path alias that makes importing the library straightforward:

// apps/dashboard/src/app/app.tsx
import { ComponentA, ComponentB } from '@micronx/common'

Nx provides additional benefits to sharing code this way by keeping track of your project's dependency graph. The relationships between your various code libraries and each dependent application can be illustrated by running nx dep-graph.

Internally, Nx uses this dependency graph to reduce the number of builds/tests that need to be run when changes are introduced. If you make a change to apps/dashboard/ and run nx affected:test, Nx will only run tests for the Dashboard micro frontend. This becomes very powerful as the dependency graph of your project grows in complexity.

Optimizations

Something unique to the micro frontend strategy is the duplication of common vendor dependencies and shared code libraries in the production JS bundles.

The Thoughwork's article touches on this in the "Common Content" section, advocating for tagging common dependencies as Webpack externals to prevent them from being included in each application's final bundle.

module.exports = (config, env) => {
  config.externals = {
    react: 'React',
    'react-dom': 'ReactDOM',
  }
  return config
}

Once Nx upgrades its React tools to Webpack 5, a new method of code optimization will be available for micro frontend projects via Module Federation. This strategy enables building shared code libraries (libs/) into the container application, removing yet another common dependency from the micro frontend bundles.

Effective TypeScript for React Applications

Graham Marlow — Mon, 13 Sep 2021 17:33:00 +0000

TypeScript and React are excellent in combination. When you sprinkle React’s expressive component model with a little strong typing, you get fewer bugs and an improved developer experience.

That said, the amount of techniques and nuances baked into the TypeScript/React combo can be overwhelming. TypeScript offers so much flexibility in structuring your React components that it’s hard to know what’s best in which situation. Those familiar with JavaScript may find themselves banging their heads against stubborn compiler warnings. Others may dread the boilerplate mountain that looms over every component.

No matter your level of experience with TypeScript, this guide is here to help you out. We’ve listed below our best practices for working with TypeScript and React, which are based on the same patterns used in our core product.

Use Interfaces Until You Need a Type

For the most part, you can use type aliases and interfaces interchangeably, as the difference between the two is subtle. You can extend existing interfaces with new properties, whereas type aliases are off-limits after declaration. Despite their similarity, it’s still useful to define a pattern so that you’re using the two styles consistently.

Here at OneSignal, we follow the heuristic “use interface until you need to use features from type". We recommend interfaces because they offer a familiar syntax for inheritance that mirrors ES2015 classes. In contrast, types are used to alias primitive values or create unions from other types.

type ButtonKind = "primary" | "secondary";

interface Props {
  kind: ButtonKind;
}

Unions Over Enums

Unlike most TypeScript features, [enum] is not a type-level addition to JavaScript but something added to the language and runtime. Because of this, it’s a feature which you should know exists, but maybe hold off on using unless you are sure.

—TypeScript Handbook

Union types and enums tend to occupy the same space in React in that they both enforce that a particular prop must be one value of a given set. However, we recommend union types over enums for a number of reasons:

They are compiler-only constructs, so they won't end up in your application's JS bundle.
They are extensible to other union types.
They are less verbose.

// Avoid enums:
enum ButtonKind {
  PRIMARY = "primary",
  SECONDARY = "secondary",
}

// Prefer union types:
type ButtonKind = "primary" | "secondary";

// Extensible to other union types:
type ExtendedButtonKind = ButtonKind | "tertiary";

Now, there are a few caveats to consider with this rule.

For one, const enum is a compile-time only enum that doesn’t increase the size of your JS bundle. Unfortunately, const enum is a disabled keyword for certain build tools, like Babel or esbuild.

You should also consider that union types and enums are not syntactically the same. You can reference the value of an enum by its declaration, avoiding direct references to a string literal. If this behavior is desirable, look to regular JS objects instead. With a handy utility type from type-fest, you can achieve the same behavior.

const ButtonStyle = {
  PRIMARY: "primary",
  SECONDARY: "secondary",
} as const;

type ButtonStyleType = ValueOf<typeof ButtonStyle>;

Extending Native HTML Elements

TypeScript ships with tons of helper types that cut down boilerplate for common React idioms. These types are particularly useful when extending native HTML elements like button or input, where you’ll want to maintain the component's original props to ensure extensibility.

Start by implementing a Button component in the two most important use-cases: clicking the button and defining its text. When typing everything manually, you get the following result:

import React from "react";

interface Props {
  children: React.ReactNode;
  onClick: () => void;
}

function Button({ children, onClick }: Props) {
  return <button onClick={onClick}>{children}</button>;
}

The first helper type to use here is React.PropsWithChildren, which automatically adds the children prop to the component:

import React from "react";

type Props = React.PropsWithChildren<{
  onClick: () => void;
}>;

function Button({ children, onClick }: Props) {
  return <button onClick={onClick}>{children}</button>;
}

Button is looking better, but the component still has to redefine props that are native to the HTML element, like onClick. This is a big problem for foundational components like Button that make up your application’s design system, as their props will grow wildly with their usage.

// This list tends to grow quickly!
type Props = React.PropsWithChildren<{
  onClick: () => void;
  type: "submit" | "button" | "reset" | undefined;
  disabled: boolean;
  // ...
}>;

Luckily, TypeScript has another utility designed for this exact purpose.

ComponentPropsWithoutRef is a generic type that supplies props for built-in React handlers and native HTML attributes. By passing in "button" as the template, you specify that the component is extending the HTML button element.

import React from "react";

type Props = React.ComponentPropsWithoutRef<"button">;

function Button({ children, onClick, type }: Props) {
  return (
    <button onClick={onClick} type={type}>
      {children}
    </button>
  );
}

The result is a component that is clean and extensible. If additional props are needed, swap the type for an interface:

import React from "react";

interface Props extends React.ComponentPropsWithoutRef<"button"> {
  specialProp: number;
}

function Button({ children, onClick, type, specialProp }: Props) {
  // ...
}

Type Refinement and Disjoint Unions

Disjoint unions (or discriminated unions) are a powerful feature that can help you refine the component props of complex structures. In short, they allow your component to support multiple variants of a shared interface.

Consider a Button component that has several theme variations, such as "primary" and "secondary". You can express this type as a string and pass it down as props.

interface Props {
  kind: string;
}

function getStyles(kind: string) {
  switch (kind) {
    case "primary":
      return styles.primary;
    case "secondary":
      return styles.secondary;
    default:
      throw new Error("invalid button kind");
  }
}

function Button({ kind }: Props) {
  const styles = getStyles(kind);
  // ...
}

While this implementation is simple, it presents significant problems.

For one, you can pass any string value into the component props, even though only "primary" and "secondary" are implemented by the component. TypeScript won't warn you that any other value throws an error.

// This passes compiler checks, yet throws an application error!
function App() {
  return <Button kind="not-a-style">click me!</Button>;
}

You can instead switch string to a union type, which offers much-needed improvements. The union type informs TypeScript of all possible values for kind, preventing any unhandled cases.

type ButtonKind = "primary" | "secondary";

interface Props {
  kind: ButtonKind;
}

function getStyles(kind: ButtonKind) {
  switch (kind) {
    case "primary":
      return styles.primary;
    case "secondary":
      return styles.secondary;
    // Default case is no longer needed!
  }
}

function Button({ kind }: Props) {
  const styles = getStyles(kind);
  // ...
}

Looking back at the component instance that is passed an invalid string literal, TypeScript now offers a helpful error:

// Error: Type '"not-a-style"' is not assignable to type 'ButtonKind'
function App() {
  return <Button kind="not-a-style">click me!</Button>;
}

Union types are great at refining props for primitive values. But what about more complex structures?

Consider that the "primary" button requires a special method, specialPrimaryMethod, that is not supported by the “secondary” variant. The component calls this special method when handling a click.

type ButtonKind = "primary" | "secondary";

interface Props extends React.ComponentPropsWithoutRef<"button"> {
  kind: ButtonKind;
  specialPrimaryMethod?: () => void;
}

function Button({ kind, onClick, specialPrimaryMethod, children }: Props) {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    if (kind === "primary") {
      if (specialPrimaryMethod) {
        specialPrimaryMethod();
      }
    } else {
      onClick?.(e);
    }
  };

  return <button onClick={handleClick}>{children}</button>;
}

Although this component compiles, the type definition of props doesn’t inform the TypeScript compiler when specialPrimaryMethod is permitted. The TypeScript compiler thinks that both “primary” and “secondary” allow the method, and that the method is optional in either case.

To further demonstrate why this is problematic, take a look at the following instances of the component. The TypeScript compiler considers all of them valid, even though some of them conflict with the intended implementation.

// Correct use-case
<Button kind="primary" specialPrimaryMethod={doSpecial}>...

// Invalid use-case: specialPrimaryMethod shouldn't be optional
<Button kind="primary">...

// Invalid use-case: secondary shouldn't support specialPrimaryMethod
<Button kind="secondary" specialPrimaryMethod={doSpecial}>...

This is where the disjoint union comes in handy. By splitting apart the interfaces for the “primary” variant and the “secondary” variant, you can achieve better compile-time type-checking.

type ButtonKind = "primary" | "secondary";

// Build separate interfaces for Primary & Secondary buttons
interface PrimaryButton {
  kind: "primary";
  specialPrimaryMethod: () => void;
}

interface SecondaryButton {
  kind: "secondary";
}

// Create a disjoint union
type Button = PrimaryButton | SecondaryButton;

// Add built-in HTML props to the disjoin union
type Props = React.ComponentPropsWithoutRef<"button"> & Button;

// You can no longer destructure props since specialPrimaryMethod
// doesn't always exist on the object.
function Button(props: Props) {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    if (props.kind === "primary") {
      // No extra if check needed!
      props.specialPrimaryMethod();
    } else {
      props.onClick?.(e);
    }
  };

  return <button onClick={handleClick}>{props.children}</button>;
}

The additional type refinement provided by the disjoint union now appropriately throws compile-time errors for invalid cases.

// All good!
<Button kind="primary" specialPrimaryMethod={() => {}}>foo</Button>

// Error: Property 'specialPrimaryMethod' is missing
<Button kind="primary">click me!</Button>

// Error: Type '{ ... specialPrimaryMethod: () => void; }' is not assignable
<Button kind="secondary" specialPrimaryMethod={() => {}}>click me!</Button>

Don’t Overuse Disjoint Unions

Disjoint unions are a powerful technique that enable general-purpose components. However, take care not to overuse them as they can lead to highly complex components.

Anytime you reach for disjoint unions, pause and consider whether the single component should instead be separated into two.

Accessible Components With Polymorphism

Polymorphic components are great for tuning markup for accessibility.

Consider a Container component that applies some styles to a div. You may want to use this Container component in situations that are better described by HTML5 elements like aside or section.

Rather than duplicating the Container component for slight alterations in its JSX, create a polymorphic component. This is as simple as including a new prop, as, that accepts a union of HTML element strings.

import React from "react";

type Props = React.PropsWithChildren<{
  as: "div" | "section" | "aside";
}>;

function Container({ as: Component = "div", children }: Props) {
  return <Component className={styles.container}>{children}</Component>;
}

The destructured alias, { as: Component }, is a convention that helps illustrate that the prop is a React component and not just a string.

The Container component now supports different HTML5 elements to better fit its use-case.

<Container as="section">
  <p>section content</p>
</Container>

Watch Out for These Bad Practices

Using `defaultProps`

Defining defaultProps on function components is marked for deprecation. You should instead assign defaults with prop destructuring:

Prefer

interface Props {
  color?: string;
}

function Button({ color = "red" }: Props) {
  /* ... */
}

Avoid

type Props = { color: string } & typeof defaultProps;

const defaultProps = { color: "red" };

function Button(props: Props) {
  /* ... */
}

Button.defaultProps = defaultProps;

Using the Non-Null Assertion Operator

The non-null assertion operator subverts TypeScript’s ability to check null values. Despite how easy it is to type, this operator can cause a ton of harm. Let TypeScript do its job!

In this case, you should instead rely on refinement or narrowing and avoid overriding the TypeScript compiler.

Prefer

const liveSafely = (x?: number) => {
  if (typeof x !== 'number') {
    throw new Error('number expected')
  }
  return x.toFixed(2)
}}

Avoid

const liveDangerously = (x?: number) => {
  return x!.toFixed(2);
};

Raising Exceptions for Exhaustive Cases

There are few cases that call for raising an exception within a React component, since it renders a blank screen if handled improperly. You can avoid catastrophic failures with Error Boundaries, but in most cases throwing an exception is unnecessary.

Instead, default to the closest acceptable user interface.

Prefer

switch (props.kind) {
  case "primary":
  default:
    return { color: "red" };
}

Avoid

switch (props.kind) {
  // ...
  default:
    throw new Error("unsupported option");
}

At OneSignal, we love empowering developers to refine their workflow and build great software. We hope these patterns help evolve your React and TypeScript codebase.

Forem: Graham Marlow

Better React Micro Frontends w/ Nx

Monorepos with Nx

Detailed example

1. Create the Nx workspace

2. Modify micro frontend Webpack configuration

3. Add in micro frontend components

4. Tie everything together

Working with Nx

Serving micro frontends

Generators

Optimizations

Effective TypeScript for React Applications

Use Interfaces Until You Need a Type

Unions Over Enums

Extending Native HTML Elements

Type Refinement and Disjoint Unions

Don’t Overuse Disjoint Unions

Accessible Components With Polymorphism

Watch Out for These Bad Practices

Using defaultProps

Using the Non-Null Assertion Operator

Raising Exceptions for Exhaustive Cases

>>We’re hiring! Check out our open positions and apply on our careers page: https://onesignal.com/careers>>

Using `defaultProps`