Skip to main content

launchClient()

import { launchClient } from '@dr.pogodin/react-utils/client';

async launchClient(Application, options): Promise<void>;

Initializes and launches ReactJS Application at the client-side.

Namely, it wraps the app with BrowserRouter and GlobalStateProvider, then hydrates it into DOM element with react-view ID, assuming [the standard SSR setup][server()] was used to generate the initial HTML markup of the page.

info

Behind the scenes, when client-side initialization module is loaded, it checks the host document for the <meta> tag injected by server, carrying app config, initial global state value, and information about application code chunks and files belonging to them. If such tag is present, it is consumed by the library. See the source code for the exact typing of that tag's payload.

For server-less usage the same data object might be bundled into an app, and passed to the library by attaching it to window.REACT_UTILS_INJECTION prior to loading the library.

The dontHydrate option allows to opt for a pure client-side rendering, instead of the hydration.

History
  • v1.47.0-alpha.8 — This function was renamed into launchClient() from the previous client() name, and it was also moved to the dedicated client-side package export @dr.pogodin/react-utils/client.
  • v1.47.0-alpha.4 — The previously synchronous client() function was turned into an asynchronous one in this version. It requires minor adjustments in the host code using it, in particular in E2E tests using E2eSsrEnv (see the updated example in its documentation).

Arguments​

Required:

  • Application - React.ComponentType - The root applciation component.

Optional:

  • options - object - Additional settings:

    • dontHydrate - boolean - By default, the app is hydrated into DOM element found by react-view ID, using React's hydrateRoot() functionality, and assuming the standard SSR setup was used to generate he initial HTML markup of the page.

      With dontHydrate flag set true React's createRoot() function is used instead to perform a clean client-side rendering into the DOM element with react-view ID.

    • initialState — object — By default the initial global state for the app is injected into the front-end from the server-side, where it can be customised during each render using the beforeRender argument of the launchServer() initialization function. This initialState option of launchClient() function provides a fallback value for the initial global state on the client-side, which is intended for server-less library use.

    The following options are forwarded to the underlying createRoot() / hydrateRoot() methods:

    • identifierPrefix — A string prefix React uses for IDs generated by useId. Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix as used on the server.

    • onCaughtError — Callback called when React catches an error in an Error Boundary. Called with the error caught by the Error Boundary, and an errorInfo object containing the componentStack.

    • onRecoverableError — Callback called when React automatically recovers from errors. Called with the error React throws, and an errorInfo object containing the componentStack. Some recoverable errors may include the original error cause as error.cause.

    • onUncaughtError — Callback called when an error is thrown and not caught by an Error Boundary. Called with the error that was thrown and an errorInfo object containing the componentStack.