White-labeling with React

White-labeling allows you to utilize one code-base across multiple brands or "skins". With React projects there are multiple ways to achieve this. The two main techniques are at compile time or at run time. The technique you use will depend on your application goals. For the Alpha Centauri Farming game we utilized compile time white-labeling but for other projects we've used run time white-labeling. In this article we will be specifically discussing run time white-labeling in React environments.

Goal

The main goal of white-labeling is to be able to use the same code base while having interchangeable assets that can be selected at run time, like say based on the domain name of the site being served. So ideally your React code does not change at all across the different "labels" and the label can be set in one place and the rest of your React application will automatically utilize it.

Implementation

With React we actually have a built in mechanism that makes this really easy: React contexts. If we create a context for our labeling then all we have to do is set the label at the top of the component hierarchy and the rest of the application can just utilize the selected label. This is similar to how themeing is often done in React.

To make this even easier I've packaged up the context and its providers and consumers into an npm package: react-whitelabel.

So how do we use this package to white-label our React app? Here is a basic example:

// ... imports

// Setup our white labels.
// We have two labels: 'cars' and 'trucks'
const labels = {
  cars: {
    logo: '/imgs/car.jpg'    // each label has a 'logo' property
  },
  trucks: {
    logo: '/imgs/truck.jpg'
  }
};

// The label to render. This would be dynamic in a real application.
const label = 'cars';

// Our main entry point, this is where we setup the provider.
export default class App extends React.Component {
  render() {
    // We render the provider and the rest of the app here.
    // For now the label is hardcoded to 'cars'. In a real
    // application this would be dynamic.
    return (
      <WhiteLabelProvider labels={labels} selectedLabel={label}>
        <div className={label}>
          <Header />
          ...
        </div>
      </WhiteLabelProvider>
    );
  }
}

// Here we utilize the selected label to render the logo.
// In this case 'src' will be '/imgs/car.jpg' because 'cars'
// is our selected label.
class HeaderComponent extends React.Component {
  render() {
    <img src={this.props.label.logo} alt='Logo' />
  }
}

// And finally we setup the Header component to utilize the
// white-label context so we can access the 'label' prop.
const Header = withWhiteLabelContext(HeaderComponent);

To see a fully working example check out the docs.

So how does this example work? First we setup our labels. This is just a Javascript object where each key maps to a label. Each label is also an object made up of referenceable keys. The WhiteLabelProvider then takes the labels and the selected label as input and then provides the selected label's object to the rest of the app. This object is accessible using a WhiteLabelConsumer or the withWhiteLabelContext wrapper. If we then made the selectedLabel dynamic, say via calling window.location.hostname, then we would have a fully run time dynamic white-label.

Also note that we are using the selected label's name as a class name in a top level div. This allows us to use the white-labeling with our CSS assets just by selecting based on the label name like .cars a { ... }.

While the react-whitelabel library is not necessary for React run time white-labeling it does make it easier and more maintainable. If you implement it yourself you will likely do the same thing the library already does for you. If your interested learning more about react-whitelabel feel free to checkout the docs or the npm page.