Take control of your JS library on your customers websites

October 29, 2023

Are you making a product where your customers have to install your JS library in their website ? You would want to take control of the version of your library used in their websites thanks to the Bootstrap Loader setup.

Why ?

Here are some reasons to consider the Bootstrap Loader setup:

You would not need to ask the customer to change your JS library URL in their websites
Iterate with features and fix bugs faster than your competitors
Improve developer productivity and effectiveness

Some products providing a JS library can be:

A traffic tracker. ex: Google Analytics
A customer support and messaging. ex: Intercom
A/B testing and experimentation. ex: Optimizely
etc…

The “Bootstrap Loader” setup we will talk about is used by these very famous libraries:

Google Tag Manager
Facebook SDK

Our use case

To illustrate it better, let’s say we are making a Google Analytics like library but with more privacy and data ownership in mind. Let’s call it: Ethic Analytics !

Our library name: ethic-analytics.js

Let’s take control !

Requirements

To set up the library version control, you would need your JS Library hosted to be accessible by an URL.
ex: https://yourcdn.com/ethic-analytics/v1.0.0/dist/main.js

Goals

Our goals here is to setup:

An endpoint from a HTTP server (static or dynamic) serving the version your library users must load. This endpoint will be called by the JS Library version loader.
ex: https://api.ethic-analytics.com/v1/lib-info or https://yourcdn.com/ethic-analytics-versions.json
A JS Library version loader.
ex: https://yourcdn.com/ethic-analytics-loader/v1.0.0/dist/main.js

Guide

Setup the HTTP server endpoint providing versions by customer

It’s a critical HTTP endpoint that will bootstrap your main library. The browser is sending an HTTP request to this endpoint and it’s returning the library script url to load in the browser. You must ensure that this HTTP server and the endpoint are highly available.

Example:
Customer website: https://bikeshop.com
HTTP Client: GET https://api.ethic-analytics.com/v1/lib-info
HTTP server: Fetch the version from the HTTP request host being “bikeshop.com”. You could fetch the version corresponding to “bikeshop.com” in a persistent storage like a database. Let’s say we assign version v1.0.0 to “bikeshop.com”
HTTP Response: { “scriptURL”: “https://yourcdn.com/ethic-analytics/v1.0.0/dist/main.js” }

For the example we are using an HTTP server but you can also use a static HTTP endpoint like “https://yourcdn.com/ethic-analytics-versions.json”. The pro of this solution is that a static file is highly available, but the con is that you expose all your customers website urls with their library versions.

Create the JS Library version loader

This library will be loaded in the customer’s website and it will fetch the version of your library that must be included in the website DOM.

Steps:

an HTTP request to fetch the script url of the library that the website musts use
insert the script in the DOM

Code:

async function init() {
  try {
    const response = await fetch("https://api.ethic-analytics.com/v1/lib-info");
    const data = await response.json();

    const scriptURL = data.scriptURL;
    // https://yourcdn.com/ethic-analytics/v1.0.0/dist/main.js

    if (document.readyState === "loading") {
      // The DOM is not yet fully loaded
      document.addEventListener("DOMContentLoaded", () => {
        insertScript(scriptURL);
      });
    } else {
      // The DOM is already fully loaded
      insertScript(scriptURL);
    }
    console.error("[ethic-analytics-loader]", `'${scriptURL}' inserted`);
  } catch (error) {
    console.error("[ethic-analytics-loader]", error);
  }
}

async function insertScript(scriptURL) {
  const script = document.createElement("script");
  script.type = "text/javascript";
  script.src = scriptURL;
  document.body.appendChild(script);
}

init();

Setup lifecycle process

Add/remove customers

When there is a new library customer, you have to insert a record in your persistent solution. When a library customer is unscribing from your product or is not respecting the terms of use, you have to delete/archive the customer corresponding record.

Administration to rollback on your library versions

You would also need to setup a rollback process to quickly switch back to the last stable and tested release version.

Conclusion

In the rapidly evolving landscape of web development, ensuring your customers have access to the most recent and stable versions of your JS library is paramount. The Bootstrap Loader Pattern offers an elegant solution to this challenge. By decoupling the loader from the main resource, developers gain unparalleled flexibility, allowing for seamless updates.

JS libraries like Google Tag Manager and the Facebook SDK have already harnessed the power of this pattern, showcasing its proven effectiveness. As you build and scale your own JS libraries, like Ethic Analytics, employing the Bootstrap Loader Pattern is a good opportunity and worth it.

Remember, it’s not just about creating great tools; it’s also about delivering them effectively.

Mathieu Schimmerling