DEV Community: Leonid Fenko

React Router Typesafe Routes v1.0.0 is Here 🎉

Leonid Fenko — Mon, 23 Jan 2023 21:28:08 +0000

React Router Typesafe Routes was updated to solve all issues emerged during its usage on several real-life projects and support relevant new features of React Router.

The library allows defining routes that provide type safety for path params, search params, state, and hash without sacrificing any features of React Router v6.

Params serialization and parsing are fully customizable. You can also validate params upon parsing, and you have control over how parsing errors are processed.

To save you a click, here is how it can be used:

import { route, numberType, booleanType, hashValues, throwable } from "react-router-typesafe-routes/dom"; // Or /native

const ROUTES = {
    USER: route(
        // This is a normal path pattern, but without leading or trailing slashes.
        // By default, path params are inferred from the pattern.
        "user/:id",
        {
            // We can override some or all path params.
            // We override id and specify that a parsing error will be thrown.
            params: { id: numberType(throwable) },
            // These are search params.
            // We specify a fallback to use in case of a parsing error.
            searchParams: { infoVisible: booleanType(false) },
            // These are state fields, which are similar to search params.
            // We use default parsing behavior, so a parsing error will result in undefined.
            state: { fromUserList: booleanType },
            // These are allowed hash values.
            // We could also use hashValues() to indicate that any hash is allowed.
            hash: hashValues("info", "comments"),
        },
        // This is a child route, which inherits all parent params.
        // Note how it has to start with an uppercase letter.
        { DETAILS: route("details/:lang?") }
    ),
};

Use Route components as usual:

import { Route, Routes } from "react-router-dom"; // Or -native
import { ROUTES } from "./path/to/routes";

// Absolute paths
<Routes>
    {/* /user/:id */}
    <Route path={ROUTES.USER.path} element={<User />}>
        {/* /user/:id/details/:lang? */}
        <Route path={ROUTES.USER.DETAILS.path} element={<UserDetails />} />
    </Route>
</Routes>;

// Relative paths
<Routes>
    {/* user/:id */}
    <Route path={ROUTES.USER.relativePath} element={<User />}>
        {/* details/:lang? */}
        {/* $ effectively defines path pattern start. */}
        <Route path={ROUTES.USER.$.DETAILS.relativePath} element={<UserDetails />} />
    </Route>
</Routes>;

Use Link components as usual:

import { Link } from "react-router-dom"; // Or -native
import { ROUTES } from "./path/to/routes";

// Absolute link
<Link
    // Path params: { id: number; lang?: string } -- optionality is governed by the path pattern.
    // Search params: { infoVisible?: boolean }.
    // State fields: { fromUserList?: boolean }.
    // Hash: "info" | "comments" | undefined
    to={ROUTES.USER.DETAILS.buildPath({ id: 1, lang: "en" }, { infoVisible: false }, "comments")}
    state={ROUTES.USER.DETAILS.buildState({ fromUserList: true })}
>
    /user/1/details/en?infoVisible=false#comments
</Link>;

// Relative link
<Link
    // Path params: { lang?: string } -- optionality is governed by the path pattern.
    // Other params remain the same.
    // $ effectively defines path pattern start.
    to={ROUTES.USER.$.DETAILS.buildRelativePath({ lang: "en" }, { infoVisible: true }, "info")}
    state={ROUTES.USER.DETAILS.buildState({ fromUserList: false })}
>
    details/en?infoVisible=true#info
</Link>;

Get typed path params with useTypedParams():

import { useTypedParams } from "react-router-typesafe-routes/dom"; // Or /native
import { ROUTES } from "./path/to/routes";

// The type here is { id: number; lang?: string }.
// Note how id can't be undefined because a parsing error will be thrown.
const { id, lang } = useTypedParams(ROUTES.USER.DETAILS);

Get typed search params with useTypedSearchParams():

import { useTypedSearchParams } from "react-router-typesafe-routes/dom"; // Or /native
import { ROUTES } from "./path/to/routes";

// The type here is { infoVisible: boolean }.
// Note how infoVisible can't be undefined because a fallback will be used upon a parsing error.
const [{ infoVisible }, setTypedSearchParams] = useTypedSearchParams(ROUTES.USER.DETAILS);

Get typed state with useTypedState():

import { useTypedState } from "react-router-typesafe-routes/dom"; // Or /native
import { ROUTES } from "./path/to/routes";

// The type here is { fromUserList: boolean | undefined }.
// Note how fromUserList can be undefined due to returning undefined upon error.
const { fromUserList } = useTypedState(ROUTES.USER.DETAILS);

Get typed hash with useTypedHash():

import { useTypedHash } from "react-router-typesafe-routes/dom"; // Or /native
import { ROUTES } from "./path/to/routes";

// The type here is "info" | "comments" | undefined.
const hash = useTypedHash(ROUTES.USER.DETAILS);

A detailed description is available at the project page.

Scroll Persistence May Not Work as Expected

Leonid Fenko — Thu, 12 Jan 2023 23:11:34 +0000

The other day I stumbled upon a peculiar problem with scroll persistence in a seemingly straightforward layout. Usually, browsers prevent layout shifts if changes are happening off-screen, and yet that wasn’t the case.

The Layout

The layout in question can be distilled into the following:

On the left, there is a component with a static header and a sticky button. Sticky elements can only stick within a container, so this component is stretched all the way down. On the right, there is long content with a dynamically updated element on top. This dynamic element changes its height unpredictably. The layout itself is a pretty straightforward grid.

The Problem

The problem is that if we scroll the page to the bottom, the content will still jump on every height change, even though browsers are usually smart enough to adjust the scroll position so that the perceived scroll position remains intact.

As a short investigation showed, the issue is that the left and right columns compete for these scroll adjustments, and browsers prioritize the elements according to their position in the DOM. The left column comes first, and therefore browsers adjust the scroll position so that we see the same part of the sticky element container. This is not practical, as we will see the sticky element regardless, and we actually want to lock the content on the right.

Moving Elements in the DOM

It can be fixed by moving the right column before the left column in the DOM and then reordering them back in place via CSS. However, this approach will break some accessibility features, most notably the button tab indices. This can be seen in the following example:

If we try to tab-navigate between buttons, the right button will come first, which is undesirable.

Removing the Competition

After some time, I realized that it was possible to remove the competition altogether. We can move the sticky element to the top and use the grid cell as its container.

This approach is a bit more complex than the initial one, but now we only have the right column and the scroll persistence works flawlessly without sacrificing accessibility.

Conclusion

Browsers are capable of preventing layout shifts on dynamic content updates. However, sometimes multiple elements compete against each other for being able to stay in place, which may lead to confusing behavior.

The ideal solution is to simply remove the competition. If that’s impossible, we can move the element that we need to lock in place so that it comes before the other elements in the DOM.

Handling Apollo Errors in React

Leonid Fenko — Sun, 13 Nov 2022 11:38:09 +0000

Introduction

Let me start with my golden principles of error handling:

If anything goes wrong, the user should be notified. No exceptions (pun intended).
We should fall into The Pit of Success. That is, error handling should just work.
We should be able to customize global error handling up to downright disabling it and implementing something completely custom.

Throughout the article, we will apply these principles to handling Apollo errors (both GraphQL and network) in React. We assume the use of Apollo Server and Typescript. SSR is also covered.

What we want

The way I see things, the best way to adhere to these principles is to implement the following:

A notification system that allows showing all kinds of messages, including errors.
A global error handler that shows error messages via the notification system. It can also log errors, send them to your error tracker, redirect to the login page in case of an authentication error, etc.
A way for us to communicate with the global error handler in order to alter its behavior (e.g. prevent it from showing an error message).

How to pass GraphQL errors to the client

A quick recap of what GraphQL errors look like (shamelessly borrowed from GraphQL Spec):

{
  "errors": [
    {
      "message": "Name for character with ID 1002 could not be fetched.",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["hero", "heroFriends", 1, "name"],
      "extensions": {
        "code": "CAN_NOT_FETCH_BY_ID",
        "timestamp": "Fri Feb 9 14:33:09 UTC 2018"
      }
    }
  ]
}

There can be multiple errors.
The message field is a description of the error intended for the developer (please don't show it to the user).
The locations and path fields point to the associated points in the request and the response field respectively. That is, errors are detached from where they occurred, and we need to implement some custom logic to parse the path field if we want to know what field caused the error. Since the null result will bubble up to the nearest nullable field, it may be tricky.
The extensions field is a map of arbitrary data associated with the error. We specifically care about its code field which is set by Apollo Server (see built-in error codes). It should be used to differentiate errors on the client side.
Errors are not a part of the GraphQL Schema. Standard fields like message, locations, path, and (Apollo-specific) extensions.code can (somewhat) be typed, but the rest of the extensions field is a wild west.

Consider treating errors as data

There is an approach to handling errors where they are added to the schema (by using unions and interfaces or by providing an additional field). It basically says "Let's add errors to GraphQL Schema to have typed errors that are co-located to where they occurred".

This approach is great, but not always viable. Some errors can happen anywhere, and there is no point in polluting your schema with them. One such example is UNAUTHENTICATED error in a private application. And sure enough, there is always a possibility of an unexpected error.

That is, with this approach, we have both actual errors and errors in data to handle. For the latter, we need to constantly repeat the error handling logic (which doesn't really conform to the "Pit of Success" principle) or create a custom link to handle them, because Apollo doesn’t know that they are, in fact, errors. In contrast, there is a built-in onError link for handling actual errors.

Personally, I think that it's best to use actual errors by default. We should switch to "errors as data" only in specific cases when we do need to know anything else other than code. We likely don’t want to use global error handling for them anyway, and there's a good chance that we can avoid them altogether.

Use null instead of NOT_FOUND in queries

There is a long-standing issue with error caching (its absence, that is), which leads to errors being rendered as a loading state on the server side. Therefore, if you're doing SSR, you might want to design your schema in such a way that there are no intentional errors in queries whatsoever. To do so, we can use null values instead of NOT_FOUND errors (see how we essentially treated errors as data here?). Note how nothing stops us from setting the response code to 404 in case of a null value, should we want so.

In fact, even if you don't do SSR, you might still benefit from discarding the NOT_FOUND errors in queries. There is no previousData analog for errors, so if you want to render a "not found" page state, it's easier to rely on data/previousData with a value of null (and, honestly, the absence of something in case of a read operation feels more data-like than error-like to me).

Most likely, all other errors can be treated as unintentional and related to the whole query (that is, we don't need to parse the path field because we just don't care). There's either a bug in our code (e.g. INTERNAL_SERVER_ERROR) or the user is doing something malicious (e.g. FORBIDDEN). Either way, it's more or less fine to SSR them as a loading state with an appropriate response code and then show a notification (or something custom) on the client side. It's not the most elegant solution, but it's the best we can do given the circumstances.

There is also a special error: UNAUTHENTICATED. Fortunately, we most likely don't need to actually render it, because it should be rendered on the server side as a redirect.

Rely on client-side validation only

Validation should be completely static. That is, we should be able to validate the user input beforehand. Therefore, any validation errors should be treated as bugs in the frontend validation logic.

It means that validation errors can and should provide extensions with detailed validation results, but we shouldn't base our logic on them. We should only apply the global handler to such errors, anticipating that these errors should never happen.

It’s worth noting that updating validation rules is technically a breaking change, so it’s perfectly fine to update client-side code in response to these changes.

Make error codes specific

In order to avoid non-standard extensions, we can make error codes more specific. For instance, don't use the NOT_FOUND code. Make it USER_NOT_FOUND, JOB_NOT_FOUND, MEANING_NOT_FOUND, and so on.

Specific error codes also aid in determining the origin of the error without parsing the path field. Especially for mutations, which are usually much more granular than queries.

For the sake of clarity: unlike queries, it's perfectly normal to use SOMETHING_NOT_FOUND errors in mutations.

Provide enum with error codes

In order to type extensions.code, we need to provide an enum with possible error codes. The easiest way to do so is to add it to the GraphQL Schema. Tools like GraphQL Code Generator can then generate the actual type that we can use.

Sadly, there is no guarantee that the enum will ever be complete. There should always be a fallback to an unknown error.

There is also no way to tell what errors the given operation may produce. We can only document them using comments.

Use standard errors

Use the built-in error codes where appropriate. Use ApolloError to create custom errors. Use standard error code format. Be consistent. Don't reinvent the wheel.

The notification system

The notification system is highly application-dependent. We can create something custom or use a library like notistack. For the sake of simplicity, we’ll assume the use of notistack from now on, but the actual implementation doesn’t really matter.

With notistack, we wrap the whole application in its provider:

import { SnackbarProvider } from "notistack";
import { RestOfTheApp } from "./RestOfTheApp";

const App = () => (
  <SnackbarProvider>
    <RestOfTheApp />
  </SnackbarProvider>
);

And then queue notifications like this:

import { useSnackbar } from "notistack";

const RestOfTheApp = () => {
  const { enqueueSnackbar } = useSnackbar();

  const handleClick = () => {
    enqueueSnackbar("Button clicked!");
  };

  return <button onClick={handleClick}>Show snackbar</button>;
};

As you can see, notistack can only be accessed from within React. Let’s see how we can connect an Apollo client instance to it.

Creating Apollo client instance within React

The obvious approach is to create an Apollo client instance within React:

import { useSnackbar } from "notistack";
import { ApolloProvider } from "@apollo/client";
import { useMemoOne } from "use-memo-one";
import { createApolloClient } from "./createApolloClient";
import { ActualApp } from "./ActualApp";

const RestOfTheApp = () => {
  const { enqueueSnackbar } = useSnackbar();
  const client = useMemoOne(() => createApolloClient({ enqueueSnackbar }), [enqueueSnackbar]);

  return (
    <ApolloProvider client={client}>
      <ActualApp />
    </ApolloProvider>
  );
};

We create an Apollo client instance with our own createApolloClient function and memoize it with useMemoOne, ensuring a semantic guarantee of memoization.

This seems suboptimal, because:

This will break if enqueueSnackbar changes because we will create a new Apollo client instance. This can be fixed with our own stableEnqueueSnackbar with a stable identity, which can call the latest enqueueSnackbar under the hood, but it will make the code even more complex. And if RestOfTheApp itself remounts for some reason, the client instance will be recreated anyway.
In the case of SSR, we can’t create an Apollo client instance within React, because the app is rendered multiple times during the data fetching process on the server side.

Creating Apollo client instance outside of React

Passing Apollo client instance in props is definitely nicer:

import { ApolloProvider, ApolloClient, NormalizedCacheObject } from "@apollo/client";
import { SnackbarProvider } from "notistack";
import { ActualApp } from "./ActualApp";

interface AppProps {
  apolloClient: ApolloClient<NormalizedCacheObject>;
}

const App = ({ apolloClient }: AppProps) => {
  return (
    <ApolloProvider client={apolloClient}>
      <SnackbarProvider>
        <ActualApp />
      </SnackbarProvider>
    </ApolloProvider>
  );
};

However, we now have to connect it to the enqueueSnackbar function. This can be done with a mediator. Let’s create a generic one:

class Dispatcher<TAction> {
  // We only need a single subscriber, which is just a callback accepting an action
  private subscriber: ((value: TAction) => void) | undefined;

  // If there is no subscriber, we store actions to dispatch them later
  private pendingActions: TAction[] = [];

  public dispatch(action: TAction): void {
    if (this.subscriber) {
      // Upon dispatch, we simply call the subscriber...
      this.subscriber(action);
    } else {
      // ... or store the action if there is no subscriber
      this.pendingActions.push(action);
    }
  }

  public subscribe(subscriber: (value: TAction) => void): () => void {
    this.subscriber = subscriber;

    // Upon subscription, we dispatch all pending actions
    this.pendingActions.forEach((action) => {
      this.subscriber?.(action);
    });

    this.pendingActions = [];

    // We return a callback to enable unsubscribing
    return () => {
      this.subscriber = undefined;
    };
  }
}

Then we can create a dispatcher for enqueueSnackbar:

import { ProviderContext } from "notistack";
import { Dispatcher } from "./Dispatcher";

const snackbarDispatcher =
  // We don't want global stateful objects on the server side
  typeof window !== "undefined" ? new Dispatcher<Parameters<ProviderContext["enqueueSnackbar"]>>() : undefined;

And here is how we can connect it to React:

import { useSnackbar } from "notistack";
import { snackbarDispatcher } from "./snackbarDispatcher";

// This hook should be used once as early as possible, though below SnackbarProvider
function useSnackbarDispatcher(): void {
  const { enqueueSnackbar } = useSnackbar();

  useEffect(() => {
    const unsubscribe = snackbarDispatcher?.subscribe((args) => enqueueSnackbar(...args));

    return () => {
      unsubscribe?.();
    };
  }, [enqueueSnackbar]);
}

The idea is to dispatch enqueueSnackbar arguments from an Apollo client instance and then pass them to enqueueSnackbar inside React. That is, snackbarDispatcher.dispatch is essentially equivalent to enqueueSnackbar.

Note that snackbarDispatcher is a global stateful object, which is a bad thing for server-side code. Using it on the server side wouldn’t make much sense anyway, but we explicitly create it only on the client side just to be safe.

The useSnackbarDispatcher hook should be used as early as possible, though below SnackbarProvider. It might be a good idea to create a custom wrapper for SnackbarProvider, which can conceal the use of useSnackbarDispatcher within itself.

The global error handler

As mentioned earlier, there is an intended way to handle errors globally: the onError link. With it, we can create a global error handler:

import { ErrorResponse } from "@apollo/client/link/error";
import { getNotifications } from "./getNotifications";
import { snackbarDispatcher } from "./snackbarDispatcher";

function globalErrorHandler(error: ErrorResponse) {
  if (snackbarDispatcher) {
    getNotifications(error).forEach((notification) => snackbarDispatcher.dispatch(notification));
  }
}

And use it like this:

import { ApolloClient, from } from "@apollo/client";
import { onError } from "@apollo/client/link/error";
import { globalErrorHandler } from "./globalErrorHandler";

function createApolloClient() {
  return new ApolloClient({
    // Other options
    link: from([
      onError(globalErrorHandler),
      // Other links
    ]),
  });
}

Let’s see how we can implement the getNotifications helper.

Parsing `ErrorResponse`/`ApolloError`

We need helpers to determine if the ErrorResponse object from the global error handler is a network error, and, if not, what are its GraphQL errors.

We also want these helpers to be usable for ApolloError objects which are returned from e.g. the useQuery hook. Fortunately, we only need the graphQLErrors and networkError fields, which are essentially the same between ErrorResponse and ApolloError.

ApolloError objects can also be thrown, so we type the error arguments as unknown.

Finally, we need to address an Apollo bug that causes GraphQL errors to appear in the network error.

import { ServerError, ServerParseError, ApolloError } from "@apollo/client";
import { GraphQLError } from "graphql";

function isNetworkError(error: unknown): error is { networkError: Error | ServerError | ServerParseError } {
  return hasNetworkError(error) && !hasGqlErrors(error);
}

function getGqlErrors(error: unknown): GraphQLError[] {
  const result: GraphQLError[] = [];

  if (hasPopulatedGqlErrors(error)) {
    result.push(...error.graphQLErrors);
  }

  if (hasUnpopulatedGqlErrors(error)) {
    result.push(...error.networkError.result.errors);
  }

  return result;
}

function hasGqlErrors(error: unknown): boolean {
  return hasPopulatedGqlErrors(error) || hasUnpopulatedGqlErrors(error);
}

function hasPopulatedGqlErrors(error: unknown): error is { graphQLErrors: ReadonlyArray<GraphQLError> } {
  return Boolean(
    error &&
      typeof error === "object" &&
      Array.isArray((error as Partial<ApolloError>).graphQLErrors) &&
      (error as ApolloError).graphQLErrors.length
  );
}

function hasUnpopulatedGqlErrors(error: unknown): error is {
  networkError: { result: { errors: ReadonlyArray<GraphQLError> } };
} {
  return Boolean(
    hasNetworkError(error) &&
      "result" in error.networkError &&
      Array.isArray(error.networkError.result.errors) &&
      error.networkError.result.errors.length
  );
}

function hasNetworkError(error: unknown): error is { networkError: Error | ServerError | ServerParseError } {
  return Boolean(error && typeof error === "object" && (error as ApolloError).networkError);
}

export { getGqlErrors, isNetworkError };

And then we can implement the getNotifications helper:

import { ProviderContext } from "notistack";
import { ErrorResponse } from "@apollo/client/link/error";
import { GqlError } from "./graphql-codegen-result";
import { getGqlErrors, isNetworkError } from "./parsing-helpers";

const NOTIFICATION_MAP: Record<GqlError, Parameters<ProviderContext["enqueueSnackbar"]>> = {
  [GqlError.InternalServerError]: ["Something went wrong :(", { variant: "error" }],
};

function getNotifications(error: ErrorResponse) {
  if (isNetworkError(error)) {
    return ["Check your network connection", { variant: "error" }];
  }

  return getGqlErrors(error).map(
    ({ extensions }) =>
      NOTIFICATION_MAP[extensions?.code ?? GqlError.InternalServerError] ??
      NOTIFICATION_MAP[GqlError.InternalServerError]
  );
}

As you can see, there can be either a network error or an array of GraphQL errors. In the latter case, we only rely on the code field. If it's absent or unknown, we fall back to INTERNAL_SERVER_ERROR.

GqlError is an enum with possible error codes generated from the GraphQL Schema (as a reminder, its completeness cannot be guaranteed).

Setting SSR response code

If there was an error during SSR, we shouldn’t return the result with a 200 status code. Therefore, we need a way to tell the renderer that there was an error. This can be done with a custom context. We can create this context on a per-request basis and pass it to globalErrorHandler via createApolloClient helper:

import { ApolloClient, from } from "@apollo/client";
import { ErrorResponse, onError } from "@apollo/client/link/error";
import { getNotifications } from "./getNotifications";
import { snackbarDispatcher } from "./snackbarDispatcher";

interface ApolloContext {
  statusCode?: number;
}

interface CreateApolloClientOptions {
  context?: ApolloContext;
}

interface GlobalErrorHandlerOptions {
  context?: ApolloContext;
}

function createApolloClient({ context }: CreateApolloClientOptions = {}) {
  return new ApolloClient({
    // Other options
    link: from([
      onError(globalErrorHandler({ context })),
      // Other links
    ]),
  });
}

function globalErrorHandler({ context }: GlobalErrorHandlerOptions = {}) {
  return (error: ErrorResponse) => {
    if (snackbarDispatcher) {
      getNotifications(error).forEach((notification) => snackbarDispatcher.dispatch(notification));
    }

    if (context) {
      // We can also set the status code depending on the error code
      context.statusCode = 500;
    }
  };
}

Note that context is only needed in the case of SSR, so it’s optional.

Handling `UNAUTHENTICATED` errors

UNAUTHENTICATED errors can be handled in a similar way, so I leave it as an exercise for the reader. Things to keep in mind:

Instead of showing a notification, we should redirect to the login page.
This requires a helper to determine if there is at least one UNAUTHENTICATED error and a mediator to connect the global error handler to the app-specific login redirect logic. Sure enough, we can use our generic parsing helpers and Dispatcher for this.
We also have to add a url field to the context to enable server-side redirects.
We most likely want to redirect to the original page after successful login. To form a proper login URL on the server side, we need to pass the current location to the global error handler alongside the context.

Overriding the global error handler

Conveniently, there is a built-in way to associate data (and even functionality) with GraphQL operations: operation context (not to be confused with our custom ApolloContext object). We can put there anything we want:

import { useQuery } from "@apollo/client";
import { MyDocument } from "./MyDocument";
import { context } from "./global-error-handler";

const { data } = useQuery(MyDocument, {
  context: context({ disableErrorNotification: true }),
});

And we can adjust the global error handler accordingly:

import { ErrorResponse } from "@apollo/client/link/error";
import { getNotifications } from "./getNotifications";
import { snackbarDispatcher } from "./snackbarDispatcher";

interface OperationContext {
  disableErrorNotification?: boolean;
}

function globalErrorHandler(error: ErrorResponse) {
  if (snackbarDispatcher) {
    const { disableErrorNotification } = error.operation.getContext() as OperationContext;

    if (!disableErrorNotification) {
      getNotifications(error).forEach((notification) => snackbarDispatcher.dispatch(notification));
    }
  }
}

// This identity function is used for context typing
function context(context: OperationContext): OperationContext {
  return context;
}

More fine-grained control can be achieved by:

using a callback accepting the ErrorResponse object and returning a boolean;
using something like {network?: boolean, gql?: Record<GqlError, boolean>} instead of boolean (we can pass it to getNotifications and filter out notifications that should be ignored).

Unfortunately, there doesn’t seem to be a way to properly type operation context. Usually, it can be done via Declaration Merging, but Apollo types are written in such a way that it’s not possible. One way to mitigate that is to use an identity function for context creation.

Conclusion

Proper error handling in Apollo is a relatively complex task, which requires effort from both backend and frontend teams. Some aspects are open for debate, especially the “where to put errors” problem. Apollo also has some bugs and implementation quirks that make the situation even worse. Even the GraphQL specification itself doesn’t make it easy.

The provided solution is not by any means definitive, but it should be general enough to cover a large number of cases.

I Made React Router v6 Type-Safe

Leonid Fenko — Sun, 17 Jul 2022 17:00:06 +0000

I updated my react-router-typesafe-routes for React Router v6. It's almost a complete rewrite, because React Router has changed quite significantly.

✨ Highlights:

Full support for nested routes.
Typing / validation of every URL part and state.
Optional inferring of path params from provided path.
Thin wrappers around React Router hooks for dealing with params in a type-safe way.
Support for web and React Native (I didn't really test React Native 😅).

A detailed description is available at the project page. I hope it will help you in making your apps a little safer.

Beware of Colons in Yarn Scripts

Leonid Fenko — Sun, 26 Sep 2021 10:42:19 +0000

Let us say you have a monorepo that uses the latest Yarn with workspace-tools plugin. There you have two child workspaces, e.g. frontend and backend. They list some linting scripts like lint:js and lint:css that use the common convention of separating the scope with a colon (:).

For obvious reasons, backend doesn't have a lint:css script. The root workspace exists only for grouping purposes and therefore doesn't have any linting scripts.

- root workspace
  - backend workspace
    - lint:js
  - frontend workspace
    - lint:js
    - lint:css

Now you want to lint all workspaces at once using the yarn workspaces foreach run command that tries to run the specified script in each workspace, including the root one. You will do something like this:

# Lint all JS
yarn workspaces foreach run lint:js

# Lint all CSS
yarn workspaces foreach run lint:css

As mentioned before, not all workspaces have the specified scripts, but that should not be a problem because the documentation states the following:

If the command is run and the script being run does not exist the child [or current] workspace will be skipped without error.

However, linting all JS results in a cryptic message in the root workspace (as a side note, this is already fixed in the canary version):

Usage Error: Couldn't find a script named "lint:js".

Linting all CSS is even funnier: the lint:css from frontend is executed three times, once for each workspace.

This is because Yarn has a little-known feature that makes any script with a colon in its name global. For lint:js, this means that there are two conflicting versions of this script in the root workspace, which leads to the "Couldn't find..." error (again, this is fixed in the canary version). For lint:css, this means that the frontend script is global, so it can be called from any workspace.

A script with a colon in its name implicitly "exists" in every workspace, so yarn workspaces foreach run will always execute it in all workspaces (if there is only one version of the script). In contrast, missing scripts without colons are properly ignored.

The issue with implicit global scripts is described in detail in this feature proposal.

Conclusions

In Yarn, use colons (:) in script names only if you want those scripts to be callable from any workspace.
The yarn workspaces foreach run command does skip a workspace if the specified script is missing there. Just make sure that the script name does not contain colons.

Client- and Server-Side Data Fetching in React

Leonid Fenko — Fri, 13 Aug 2021 11:21:19 +0000

This is an overview of client- and server-side data fetching approaches in React 17, their pros and cons, and the way upcoming Suspense for Data Fetching will change them.

So how do we fetch?

React supports the following fetching approaches:

Fetch-on-Render: fetching is triggered by render.
Fetch-Then-Render: we start fetching as early as possible and render only when the data is ready.
Render-as-You-Fetch: we start fetching as early as possible and then start rendering immediately, without waiting for the data to be ready. In a sense, Fetch-Then-Render is a special case of Render-as-You-Fetch.

It goes without saying that the fetching approaches can differ between client and server environments, and even between different parts of an application. For instance, consider how Apollo works.

On the server side, if we use getDataFromTree, we implement Fetch-on-Render, because we render the app to trigger fetching. Or, we can use Prefetching instead and get either Fetch-Then-Render or Render-as-You-Fetch, depending on when we start rendering.

On the client side, Fetch-on-Render is the default approach, because that's how the useQuery hook works. We can also use Prefetching and essentially get Render-as-You-Fetch.

Finally, on the client side, we can delay the initial render until Prefetching is complete to implement Fetch-Then-Render, but it's likely not a very good idea.

In fact, we can mix the fetching approaches. For instance, on the client side, we can move all page queries to the page component and render its content only when all data arrives. This way, the page content will effectively use the Fetch-Then-Render approach, though the page component itself will use either Fetch-on-Render or Render-as-You-Fetch.

Throughout the article, we will focus on "pure" forms of the fetching approaches.

Show me the code!

The following examples give a rough idea of what the fetching approaches look like on both the server and the client sides (as of React 17).

Fetch-on-Render

/** Server-side part. Express middleware. */
async function ssrMiddleware(_, res) {
    /** Request-specific store for our data. */
    const store = createStore();

    const app = createElement(App, { store });

    /**
     * Render the app (possibly multiple times) and wait for
     * registered promises.
     * Server-side fetching can be disabled.
     */
    if (process.env.PREFETCH) {
        await getDataFromTree(app);
    }

    /**
     * Render the final variant of the app and send it alongside the
     * store.
     */
    res.send(
        `<!doctype html>
        <body>
            <div id="root">${renderToString(app)}</div>
            <script>window.STORE=${JSON.stringify(
                store.extract()
            )}</script>
            <script src="bundle.js"></script>
        </body`
    );
}

/**
 * Client-side part. Hydrate the received markup with the store from
 * SSR.
 */
hydrate(
    createElement(App, { store: createStore(window.STORE) }),
    document.getElementById("root")
);

/** Isomorphic App component. */
const App = ({ store }) => {
    const [user, refetch] = useQuery(store, "user", fetchUser);

    return (
        <div>
            {user ? user.name : "Loading..."}
            <button onClick={refetch}>Refetch</button>
        </div>
    );
};

/** A hook for all fetching logic. */
function useQuery(store, fieldName, fetchFn) {
    /** Server-side-only helper from the getDataFromTree utility. */
    const ssrManager = useSsrManager();

    /**
     * If no data on the server side, fetch it and register the
     * promise.
     * We do it at the render phase, because side effects are
     * ignored on the server side.
     */
    if (ssrManager && !store.has(fieldName)) {
        ssrManager.add(
            fetchFn().then((data) => store.set(fieldName, data))
        );
    }

    /**
     * If no data on the client side, fetch it.
     * We do it in a passive effect, so render isn't blocked.
     */
    useEffect(() => {
        if (!store.has(fieldName)) {
            fetchFn().then((data) => store.set(fieldName, data));
        }
    });

    /** Subscribe to a store part. */
    const data = useStoreValue(store, fieldName);

    const refetch = () =>
        fetchFn().then((data) => store.set(fieldName, data));

    return [data, refetch];
}

Fetch-Then-Render

/** Server-side part. Express middleware. */
async function ssrMiddleware(_, res) {
    /** Request-specific store for our data. */
    const store = createStore();

    const app = createElement(App, { store });

    /**
     * Fill the store with data.
     * Server-side fetching can be disabled.
     */
    if (process.env.PREFETCH) {
        await App.prefetch(store);
    }

    /**
     * Render the first and final variant of the app and send it
     * alongside the store.
     */
    res.send(
        `<!doctype html>
        <body>
            <div id="root">${renderToString(app)}</div>
            <script>window.STORE=${JSON.stringify(
                store.extract()
            )}</script>
            <script src="bundle.js"></script>
        </body`
    );
}

/**
 * Client-side part. Hydrate the received markup with the store from
 * SSR, enriched by cleint-side initial fetching.
 */
hydrate(
    createElement(App, {
        store: await App.prefetch(createStore(window.STORE)),
    }),
    document.getElementById("root")
);

/** Isomorphic App component. */
const App = ({ store }) => {
    const [user, refetch] = useQuery(store, "user", fetchUser);

    return (
        <div>
            {user ? user.name : "Loading..."}
            <button onClick={refetch}>Refetch</button>
        </div>
    );
};

/** A function for initial fetching. */
App.prefetch = async (store) => {
    if (!store.has("user")) {
        /** We explicitly prefetch some data. */
        store.set("user", await fetchUser());
    }

    return store;
};

/** A hook for fetching in response to a user action. */
function useQuery(store, fieldName, fetchFn) {
    /** Subscribe to a store part. */
    const data = useStoreValue(store, fieldName);

    const refetch = () =>
        fetchFn().then((data) => store.set(fieldName, data));

    return [data, refetch];
}

Render-as-You-Fetch

/** Server-side part. Express middleware. */
async function ssrMiddleware(_, res) {
    /** Request-specific store for our data. */
    const store = createStore();

    const app = createElement(App, { store });

    /**
     * Fill the store with data.
     * Server-side fetching can be disabled.
     */
    if (process.env.PREFETCH) {
        const prefetchPromise = App.prefetch(store);

        /** We "render-as-we-fetch", but it's completely useless. */
        renderToString(app);

        await prefetchPromise;
    }

    /**
     * Render the final variant of the app and send it alongside the
     * store.
     */
    res.send(
        `<!doctype html>
        <body>
            <div id="root">${renderToString(app)}</div>
            <script>window.STORE=${JSON.stringify(
                store.extract()
            )}</script>
            <script src="bundle.js"></script>
        </body`
    );
}

/**
 * Client-side part. Start client-side initial fetching and immediately
 * hydrate the received markup with the store from SSR.
 */
const store = createStore(window.STORE);
App.prefetch(store);
hydrate(createElement(App, { store }), document.getElementById("root"));

/** Isomorphic App component. */
const App = ({ store }) => {
    const [user, refetch] = useQuery(store, "user", fetchUser);

    return (
        <div>
            {user ? user.name : "Loading..."}
            <button onClick={refetch}>Refetch</button>
        </div>
    );
};

/** A function for initial fetching. */
App.prefetch = async (store) => {
    if (!store.has("user")) {
        /** We explicitly prefetch some data. */
        store.set("user", await fetchUser());
    }

    return store;
};

/** A hook for fetching in response to a user action. */
function useQuery(store, fieldName, fetchFn) {
    /** Subscribe to a store part. */
    const data = useStoreValue(store, fieldName);

    const refetch = () =>
        fetchFn().then((data) => store.set(fieldName, data));

    return [data, refetch];
}

Fetch-on-Render vs Fetch-Then-Render vs Render-as-You-Fetch

Fetching start time

As you can see, Fetch-Then-Render and Render-as-You-Fetch make it possible to start fetching earlier, because the requests don't wait for the render to kick them off.

Rendering without data

Fetch-Then-Render is simple: a component will never be rendered without its data.

With Fetch-on-Render or Render-as-You-Fetch, however, the data can arrive after the render, so the component has to be able to display some "no-data" state.

Fetching waterfalls

Fetching waterfalls are situations where requests that should have been parallelized are unintentionally made sequential.

Fetch-on-Render makes it easy to create such waterfalls, because the requests are decentralized. Some parent can fetch its data, then pass this data to its newly-rendered child, which itself can trigger a request that doesn't use the passed data at all. That's a clear waterfall.

Fetch-Then-Render, on the other hand, forces the requests to be centralized (most likely on a per-page basis), thereby eliminating the risk of creating these waterfalls. However, now that we've grouped all the requests into a single promise, we therefore have to wait for all of them to complete before we can render, which is not ideal.

Render-as-You-Fetch also forces the requests to be centralized, but, since render is not delayed, we can show pieces of data as they arrive.

Number of server-side renders

As of React 17, we can't wait for data during render.

For Fetch-Then-Render, it's not a problem. Since the requests are centralized, we can simply wait for them all and then render the app only once.

Fetch-on-Render, however, forces us to render the app at least two times. The idea is to render the app, wait for all the initiated requests to complete, and then repeat the process until there are no more requests to wait for. If it seems inefficient and not ready for production, don't you worry: this approach has long been used by Apollo.

Render-as-You-Fetch is very similar to Fetch-Then-Render, but slightly less efficient (it requires two renders, one of which is useless). In fact, it shouldn't be used on the server side at all.

Encapsulation of the fetching logic

With Fetch-on-Render, it's easy to encapsulate both client- and server-side code in a single hook.

In contrast, Fetch-Then-Render and Render-as-You-Fetch force us to split the fetching logic. On one hand, there is the initial fetching. It occurs before render (outside of React), and it can happen on both the server and the client sides. On the other hand, there is the client-side-only fetching in response to user actions (or other events), which still happens before render, but most likely resides within React.

Access to React-specific data

In case of Fetch-on-Render, everything happens inside React. It means that the fetching code has access to props (we most likely care about URL params), and we are guaranteed to always fetch the data for the right page.

Fetch-Then-Render and Render-as-You-Fetch are a bit more complicated. The initial fetching happens outside of React. Hence, we have to do some extra work to determine which page we're on and what the URL params are.

The event-driven fetching, however, usually resides within React and has access to props and everything else.

What will change in React 18?

React 18 will support Suspense for Data Fetching.

With the recommended API, either fetching approach will result in a single render on the server side (in the sense that we won't discard previously rendered parts).

With Suspense in general, we will render a component only if its data is ready, because otherwise the component will suspend, and we will try again when the data is ready.

All other mentioned pros and cons will remain the same.

As you can see, Render-as-You-Fetch will work equally well on both the server and the client sides, and it will completely replace Fetch-Then-Render, because the latter just won't have any advantages left.

Fetch-on-Render will remain available as a more convenient (though less efficient) alternative.

Summary

	Fetch-on-Render	Fetch-Then-Render	Render-as-You-Fetch
Fetching start time	❌ Fetching is delayed until render	✔️ Fetching is started as soon as possible	✔️ Fetching is started as soon as possible
Rendering without data (no Suspense)	❌ Always	✔️ Never	❌ Sometimes
Rendering without data (Suspense)	✔️ Never	⚠️ It's completely replaced by Render-as-You-Fetch	✔️ Never
Fetching waterfalls	❌ Implicit waterfalls, but we show data independently	❌ Only explicit waterfalls, but we show "all or nothing"	✔️ Only explicit waterfalls, and we show data independently
Number of server-side renders (no Suspense)	❌ At least two renders	✔️ A single render	❌ Two renders, one of which is useless
Number of server-side renders (Suspense)	✔️ A single render	⚠️ It's completely replaced by Render-as-You-Fetch	✔️ A single render
Encapsulation of the fetching logic	✔️ Yes	❌ No	❌ No
Access to React-specific data	✔️ Yes	❌ The initial fetching is done outside of React	❌ The initial fetching is done outside of React
Usage with Suspense for Data Fetching	✔️ It's less efficient but more convenient	⚠️ It's completely replaced by Render-as-You-Fetch	✔️It's the recommended approach

My solution for React Router type safety

Leonid Fenko — Fri, 30 Jul 2021 14:52:48 +0000

I like my code fully typed. Unfortunately, type safety for route parameters has never been a strong suit of React Router.

If all you need is to build a path with parameters, the use of generatePath will give you some typing, albeit not perfect. However, there is no built-in way to build a query or a hash, let alone type them, and there is no type safety for a route state either.

Things get even worse when it comes to parsing. There is no built-in way to parse a query or a hash, and all typing is almost exclusively done by casting, which is error-prone.

There are some libraries for providing this type safety, but they are more or less incomplete and restrictive. The best I've seen so far is typesafe-routes, but it offers no type safety for a route state and a hash, and it puts restrictions on what paths can be used. For instance, it doesn't support custom regexps for parameters.

The solution

Enter react-router-typesafe-routes. It tries to be as comprehensive, extensible, and non-restrictive as possible.

Route definition

import { route, path, query, hash } from "react-router-typesafe-routes";
import { state } from "./path/to/state";

const someRoute = route(path("/path/:id"), query(), hash(), state());

There are several helpers for processing different parts of a route:

path uses generatePath to build a path string, making it possible to use any path template that's compatible with React Router. When it comes to parsing, React Router extracts params from a path string, and path performs various checks on these params to ensure that they belong to the specified path template. By default, path infers types of path params from a path template in the same way as generatePath does.
query uses (configurable!) query-string to build and parse a query string. By default, query uses the same types for query params as query-string does.
hash just takes care of the # symbol while building and parsing a hash string. By default, hash uses the string type for a hash.
state is an ad-hoc helper written by the user. The library doesn't provide a generic helper for route state processing.

As expected, the types can be improved:

import { route, path, query, hash, param } from "react-router-typesafe-routes";

const someRoute = route(
    path("/path/:id(\\d+)?", { id: param.number.optional }),
    query({ search: param.string.optional("") }), // Use "" as a fallback
    hash("about", "subscribe")
);

The param helper defines a set of transformers that transform values while building and parsing. The built-in transformers are param.string, param.number, param.boolean, param.null, param.date, param.oneOf(), and param.arrayOf().

The optional modifier means that the corresponding value can be undefined. An unsuccessful parsing of an optional parameter will also result in undefined. It's possible to specify a fallback value that will be returned instead of undefined. This should be particularly useful for query params.

Note that query params are optional by their nature. React Router doesn't consider the query part on route matching, and the app shouldn't break in case of manual URL changes.

The transformers are very permissive. It's possible to (natively!) store arrays in a query and even in a path, and it's possible to write custom transformers for storing any serializable data.

Route usage

Use Route components as usual:

import { Route } from "react-router";
import { someRoute } from "./path/to/routes";

<Route path={someRoute.path} />;

Use Link components as usual:

import { Link } from "react-router-dom";
import { someRoute } from "./path/to/routes";

// Everything is fully typed!
<Link to={someRoute.build({ id: 1 }, { search: "strawberries" }, "about")} />;
<Link to={someRoute.buildLocation({ state: "private" }, { id: 1 }, { search: "strawberries" }, "about")} />;

Parse params with usual hooks:

import { useParams, useLocation } from "react-router";
import { someRoute } from "./path/to/routes";

// You can use useRouteMatch() instead of useParams()
const { path, query, hash, state } = someRoute.parse(useParams(), useLocation());

Parse only what you need:

import { useParams, useLocation } from "react-router";
import { someRoute } from "./path/to/routes";

// Again, you can also use useRouteMatch()
const path = someRoute.parsePath(useParams());
const query = someRoute.parseQuery(useLocation());
const hash = someRoute.parseHash(useLocation());
const state = someRoute.parseState(useLocation());

Notes

A more detailed description is available at the project page. The library requires battle-testing and has yet to reach version 1.0.0.

Stretching body to full viewport height: the missing way

Leonid Fenko — Tue, 13 Jul 2021 11:50:57 +0000

Suppose you're making a sticky footer or centering some content relative to the viewport. You want to stretch the body element to the full height of the browser viewport while also letting it grow even further to match its content. This task was surely solved a bazillion times, and it should be as easy as pie. Right? Right?

The state-of-the-art way

Sure! Applying min-height: 100vh to the body element should do the trick. Here, 100vh means that the initial body height will take 100% of the viewport height, whereas the use of min-height instead of height will let the body element grow even more if necessary. Isn't it exactly what we need?

Well... Almost. If we open such a page in a typical mobile browser (such as iOS Safari or Android Chrome), it will be scrollable regardless of the size of its content. Even if the page has no content at all, its bottom will still disappear beneath the bottom UI panel of the browser!

The reason for this is fairly simple. UI elements in these browsers shrink after the scroll, providing additional space for the actual content. A height of 100vh corresponds to the maximum possible viewport height. Since the initial viewport height is smaller, the body element with a min-height of 100vh initially exceeds the viewport height regardless of its content.

The known fix for this issue looks like this:



html {
    height: -webkit-fill-available; /* We have to fix html height */
}

body {
    min-height: 100vh;
    min-height: -webkit-fill-available;
}

This solution has a minor glitch in Chrome: when the browser height increases, the body height stays the same, getting out of sync with the viewport height. Aside from that, this approach solves the issue.

However, we now have to fix the html height. If that's the case, shouldn't we use an older, more robust solution?

The old-school way

Since we couldn't avoid fixing the html height, let's try the good old way that involves passing a height of 100% from the html element.

Let's apply min-height: 100% to the body element, where 100% is the full height of its parent (namely, html). A percentage height on a child requires its parent to have a fixed height, so we have to apply height: 100% to the html element, thereby fixing its height to the full viewport height.

Since the percentage height of the html element in mobile browsers is calculated relative to the minimal viewport height, the above-mentioned scroll issue doesn't bug us anymore!



html {
    height: 100%; /* We still have to fix html height */
}

body {
    min-height: 100%;
}

This solution is not as pretty as the 100vh one, but it's been used since time immemorial, and it will work, that's for sure!

Well... Not quite. Apparently, the gradient applied to such a body element will be cut at the html height (in other words, at the viewport height, or, to be more precise, at the minimal viewport height).

It happens because of the fixed html height, and it doesn't matter whether it's height: 100% or height: -webkit-fill-available.

Of course, this can be "fixed" by applying the gradient to the body content, but that's just not right. The page background should be applied to the body element, and the html element should stretch to its content. Can we achieve that?

The missing way

I suggest another way of stretching the body element to the full viewport height without the above-mentioned issues. The core idea is to use flexbox, which enables a child element to stretch even to a parent with non-fixed dimensions while retaining the ability to grow further.

First, we apply min-height: 100% to the html element to stretch it to the full minimal viewport height. Then we use display: flex and flex-direction: column to turn it into a flex-container with a vertical main axis. Finally, we apply flex-grow: 1 to the body element, thereby stretching it to the html height.

The align-self property of the body element implicitly has the stretch value, so the body width already matches the html width.



html {
    min-height: 100%; /* Look, it's not fixed anymore! */

    display: flex;
    flex-direction: column;
}

body {
    flex-grow: 1;
}

Now both html and body can stretch to their content, and, since we're using the percentage height, there are no issues with mobile browsers whatsoever. Neat!

Notes

It should be obvious that the flexbox-based solution works for any depth. It can easily be used in cases where the content is being rendered to an element inside the body, and not the body element itself. It's a typical scenario with React or Vue, for example.
As you might've noticed, the direction of the main axis of the flex-container shouldn't matter. I just think that the vertical axis is more elegant in this case, and I didn't really test the other variant. I don't see how it can possibly break, but who knows.
The flexbox-based solution doesn't work in IE. Not at all. But you don't support it anyway, do you?

DEV Community: Leonid Fenko

React Router Typesafe Routes v1.0.0 is Here 🎉

Scroll Persistence May Not Work as Expected

The Layout

The Problem

Moving Elements in the DOM

Removing the Competition

Conclusion

Handling Apollo Errors in React

Introduction

What we want

How to pass GraphQL errors to the client

Consider treating errors as data

Use null instead of NOT_FOUND in queries

Rely on client-side validation only

Make error codes specific

Provide enum with error codes

Use standard errors

The notification system

Creating Apollo client instance within React

Creating Apollo client instance outside of React

The global error handler

Parsing ErrorResponse/ApolloError

Setting SSR response code

Handling UNAUTHENTICATED errors

Overriding the global error handler

Conclusion

I Made React Router v6 Type-Safe

Beware of Colons in Yarn Scripts

Conclusions

Client- and Server-Side Data Fetching in React

So how do we fetch?

Show me the code!

Fetch-on-Render

Fetch-Then-Render

Render-as-You-Fetch

Fetch-on-Render vs Fetch-Then-Render vs Render-as-You-Fetch

Fetching start time

Rendering without data

Fetching waterfalls

Number of server-side renders

Encapsulation of the fetching logic

Access to React-specific data

What will change in React 18?

Summary

My solution for React Router type safety

The solution

Route definition

Route usage

Notes

Stretching body to full viewport height: the missing way

The state-of-the-art way

The old-school way

The missing way

Notes

Parsing `ErrorResponse`/`ApolloError`

Handling `UNAUTHENTICATED` errors