hops-react

Please see the main Hops Readme for general information and a Getting Started Guide.

This is a preset for Hops that enables React, JSX, React-Helmet Async and React-Router support in Hops applications. It also supports the JSX Transform.

hops-react's main runtime exports are a couple of React components that allow implementers to declaratively control server (or system) behavior. Additionally, hops-react features full support for react-router's and react-helmet-async's components.

hops-react provides all three types of hops-bootstrap mixin types. Its core mixin uses hops-webpack's configureBuild hook to add some settings specific to React, for example support for JSX syntax.

Its runtime, i.e. browser and server, mixins are a bit more interesting as they are hops-react's only default render mixins. They set up React for client- and server-side rendering. Additionally, they provide mixin hooks of their own to allow you to add your own features, for example Redux support.

During application startup, hops-react runs a check to determine if certain npm packages are installed multiple times. If you see warnings telling you that this is the case, you will want to make sure you get rid of these duplicates, as they will almost certainly break things in interesting ways.

Installation

Add this preset and its peer dependencies react, react-dom, react-helmet-async and react-router-dom to your existing Hops React project:

npm install --save hops-react react react-dom react-helmet-async react-router-dom

If you don't already have an existing Hops project read this section on how to set up your first Hops project.

Usage

After installing this preset your main entry file (either referenced via package.json "main" entry or named as index.js) must default export render(<MyApp />) from hops-react.

import { render } from 'hops-react';

export default render(<h1>Hello World!</h1>);

Check out this integration test as an example for how to use this preset.

Consumer API

render(element[, options]): UniversalRenderImplementation

render() is hops-react's main export. You are expected to call it in your applications main entry file and it is essentialy a shorthand: it creates and bootstraps a mixin container and calls its render method.

render accepts two arguments: a react element and an optional options object. hops-react will use the contents of options.router to configure the React Router instances it controls.

import { render } from 'hops-react';

export default render(<h1>hello world</h1>);

The render function serves two main purposes: 'universalifying' or 'isomorphizing' you application, i.e. making sure your app's code can run both on a server and in a browser, and integrating hops's build and runtime environments.

importComponent(moduleLoader, [exportResolver])

Using the importComponent helper, you can asynchronously require components into your application to help you reduce asset sizes. It works similarly to react-loadable, but is deeply integrated with hops and e.g. supports server-side-rendering.

import { importComponent } from 'hops-react';

const Home = importComponent(
  () => import('./home'),
  ({ Home }) => Home
);

export default () => <Home />;

If you do not specify an exportResolver, importComponent will fall back to the imported modules default export.

importComponent itself returns a React component supporting some props that enable you to control module loading and (placeholder) rendering.

import { importComponent } from 'hops-react';

const About = importComponent(
  () => import('./about'),
  (namespace) => namespace.About
);

const loader = (load) =>
  Promise.race([
    new Promise((resolve, reject) => setTimeout(reject, 10000)),
    load(),
  ]);

const render = ({ Component, error, loading, ...props }) => {
  return !(error || loading) ? <Component {...props} /> : null;
};

export default () => <About loader={loader} render={render} />;

Components loaded using importComponent (and their dependencies) will be placed in separate chunks, i.e. asset files. hops-react makes sure that all asset files containing modules used for server-side rendering are referenced in the initial HTML output.

<Header name="String" value="String" />

With this component, you can declaratively set arbitrary HTTP headers from your React application. On the client side, it is effectively a no-op.

import { Header } from 'hops-react';

export default () => <Header name="X-Foo" value="Bar" />;

<Miss />

This component allows you to instruct hops-react to call Express.js' middleware next function. On the client side, it is effectively a no-op.

import { Miss } from 'hops-react';

export default () => <Miss />;

Place this side-effect component after the last <Route /> in your React Router's <Switch /> component to signal the server that it should respond with a 404 status code.

<Status code={Number} />

This component enables you to instruct hops-react to send a different HTTP status code than the default of 200. On the client side, it is effectively a no-op.

import { Status } from 'hops-react';

export default () => <Status code={404} />;

withServerData(Component): HigherOrderComponent

Wrap your component with this HoC to get access to the prop serverData which contains all values of mixins that have implemented the enhanceServerData hook.

useServerData(): ServerData

React hook for accessing the serverData-property from inside a functional component.

<ServerDataContext.Consumer>{data => /* render something */}</ServerDataContext.Consumer>

If you don't want to use the above mentioned HoC or React hook you can also use this React Context consumer instead. It will accept a function as a child component and pass the serverData object to it. You can also use ServerDataContext as contextType or in the useContext React hook.

withConfig(Component): HigherOrderComponent

Wrap your component with this HoC to get access to the prop config which contains all settings.

useConfig(): Config

React hook for accessing the config-property from inside a functional component.

<ConfigContext.Consumer>{data => /* render something */}</ConfigContext.Consumer>

If you don't want to use the above mentioned HoC or React hook you can also use this React Context consumer instead. It will accept a function as a child component and pass the config object to it. You can also use ConfigContext as contextType or in the useContext React hook.

Configuration

Preset Options

This preset has no preset configuration options.

Render Options

This preset has no runtime configuration options.

Mixin Hooks API

Caution: Please be aware that the mixin hooks are not part of the SemVer API contract. This means that hook methods and signatures can change even in minor releases. Therefore it's up to you to make sure that all hooks that you are using in your own mixins still adhere to the new implementation after an upgrade of a Hops packages.

render([req, res, next]): void (override) runtime/browser/server

This method is being called whenever you call the main render method. In a server-side, i.e. Node.js, environment it receives the usual arguments any Express middleware receives: req, res, and next. In a client-side, i.e. browser, environment it receives no arguments whatsoever.

const { Mixin } = require('hops-mixin');

module.exports = class FooMixin extends Mixin {
  render(req, res, next) {
    if (req) {
      // server
    } else {
      // browser
    }
  }
};

You will not usually have to override this method as it exposes the following mixin hooks to alter its behaviour. In a server-side environment, a fresh mixinable container is being created for every request, including new mixin instances.

bootstrap([req, res]): void (parallel) runtime/browser/server

Within this method, you are expected to set up your application. Your implementation will receive both Express' req and res objects for you to do whatever you like with. If you need to do something asynchronous in this method, just return a Promise.

const { Mixin } = require('hops-mixin');

module.exports = class FooMixin extends Mixin {
  bootstrap(req, res) {
    if (req) {
      // server
    } else {
      // browser
    }
  }
};

Remember you can register custom middlewares using hops-express instead of implementing elaborate request or response handling logic inside your runtime mixin.

enhanceElement(element): element (compose) runtime/browser/server

With this method, you can wrap the React root element with additional components, like Redux' Provider. If you need to do something asynchronous in this method, just return a Promise resolving to the wrapped element.

const { Mixin } = require('hops-mixin');

module.exports = class FooMixin extends Mixin {
  enhanceElement(element) {
    return element;
  }
};

fetchData(data, element): data (pipe) runtime/browser/server

Most applications need some sort of data. Implement this method in your mixin, to fetch said data before rendering and return an object with that additional data. If you need to do something asynchronous in this method, just return a Promise resolving to the data.

const { Mixin } = require('hops-mixin');

module.exports = class FooMixin extends Mixin {
  fetchData(data, element) {
    return { ...data, foo: 'bar' };
  }
};

getTemplateData(data): data (pipe) server

In case you need to gather additional template data after React rendering, e.g. if you are using styled components, you can add the required data by implementing this hook in your custom mixin. To do so asynchronously, have this method return a Promise resolving to the extended data.

const { Mixin } = require('hops-mixin');

module.exports = class FooMixin extends Mixin {
  getTemplateData(data) {
    return { ...data, baz: 'qux' };
  }
};

This hook is only used for server-side rendering, i.e. it will not be called in the browser.

enhanceServerData(serverData, req, res): serverData (pipe) server

In some cases you need to share data from the server-side to the client-side (for example request specific data or derived data). For these circumstances you can implement the enhanceServerData() hook (which will get passed the previous serverData object and Express request and response objects) and add your key/value pairs that you want to make accessible on the client-side via the above mentioned HoC or Context consumer.

getServerData(): serverData (override) runtime/browser/server

Returns the serverData produced by enhanceServerData on server and client.