How to White-label a Single-Page App

What Does White-label Mean?

White-labelling is when one company produces a product for another company to resell with their own label.

Think generic cereal for a good example.

Safeway, Kroger, Schnucks, and the Piggly Wiggly are likely not making their own Toasted Whole-grain Oats Cereal (Cheerios). Instead, they’re contracting with a generic cereal producer to put a custom label on the product.

Why White-label?

Kroger purchases white-labelled products so that they don’t have to make them themselves. Grocery stores don’t want the risk and expense of producing twenty different kinds of cereal, as well as all the other foods under their label.

The cereal producers sell white-labelled goods in order to access new markets. It’s easier to sell via an already established brand, so marketing things as Kroger brand is much easier than as “Brian’s Cereal Co”.

For software, it’s much the same. If you’re selling a service, it is far easier to access an existing market than to build one from scratch. And if you are a company that needs to offer a service that’s outside your core product, the case is not too different from any other build-vs-buy decision.

What to Look for in a White-label System

When you balance features against ease of deployment and maintainability in your white-label app, your list of priorities might look something like this:

• Custom branding, same functionality>
• Branding determined by the URL
• Easy to add new versions of the app (with different logos, color schemes, copy, etc)
• Easy to deploy a change to all versions at once.

So with these goals in mind, here’s the process that’s worked out well for us on these last couple of projects.

How to Do It

• Frontend code is built and deployed to an S3 bucket.

• There is an AWS Cloudfront distribution fronting the S3 bucket.

  • Add your SSL certificate to the Cloudfront distribution. It will need to include all domains that should represent your app. If you don’t know them all up-front, you can change the certificate later, add a new distribution, or use a wildcard certificate if they will all be subdomains under your control.
  • Any domains that will be used for your server should be CNAMEd to your cloudfront url. It will look something like my-whitelabel.awesomeservice CNAME d2379hnhjoggu0.cloudfront.net.
  • If you have an api, it’s a good idea to add a cloudfront behavior to send /api/* requests to your api (that way, you can avoid worrying about CORS). Be sure to turn off all caching for this behavior, and to forward all headers. To mimic this during development, I like to use webpack dev server’s proxy option.

• Upon a push to master, a CI/CD server creates a minified production build, and copies it up to the S3 bucket. Then it creates an invalidation for the cloudfront distribution, saying “there’s a new version out there, pick up the new code!”

• When the code lands in a user’s browser, it needs to figure out what branding to display. The javascript should look through a list of potential domains where it might be hosted, and choose the branding associated with the one that matches window.location.origin.

Considerations

We think this works pretty well on its own, but there are some things to think about.

First, each version of the white-label must include information about all configuration options. The configuration doesn’t take up a significant portion of bundle size but this may be something to look into.

Second, adding a new version of the app isn’t difficult but it does require a code change and deploy. Consider making a simple control page where a non-technical admin could add a new domain or change branding for an existing one. For our two projects, an admin page didn’t fit with the clients’ timeline goals, but they wouldn’t be difficult to add in the future.

Finally, every white-label project is going to come with its own unique requirements so be ready to customize your process as necessary.

Author: Brian, Senior Software Developer

—

Devetry partners with clients to identify critical needs and build custom software. Understanding client needs comes first. Choosing the right technology comes second. Learn more.