⚠️ Renamed browser builds to bundles ⚠️

WunderbarNetwork · Jul 25, 2023 · bf4ad29 · bf4ad29
1 parent 1b2a8b4
commit bf4ad29
Show file tree

Hide file tree

Showing 7 changed files with 355 additions and 41 deletions.
diff --git a/...rkflows/upload-browser-builds-to-cdn.yaml → .github/workflows/upload-bundles-to-cdn.yaml b/...rkflows/upload-browser-builds-to-cdn.yaml → .github/workflows/upload-bundles-to-cdn.yaml
@@ -1,12 +1,12 @@
-name: Upload browser builds to CDN
+name: Upload bundles to CDN
 
 on:
   release:
     types: [published]
 
 jobs:
   upload:
-    name: Upload Browser Builds to GCS
+    name: Upload Bundles to GCS
 
     strategy:
       matrix:
@@ -24,11 +24,11 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: 'yarn'
 
-      - name: Install dependencies & build lib folder
+      - name: Install dependencies & build lib output
         run: yarn --network-concurrency 8 || yarn --check-files --cache-folder .ycache && rm -rf .ycache
 
-      - name: Debug - Output Browser Build Files To Be Copied
-        run: ls -la $GITHUB_WORKSPACE/lib/browser
+      - name: Debug - output bundles file list
+        run: ls -la $GITHUB_WORKSPACE/lib/bundles
 
       - name: Check Google Cloud SDK Presence
         id: check-gcloud-sdk
@@ -66,9 +66,9 @@ jobs:
           VERSION=$(node -p "require('./package.json').version")
           MAJOR_MINOR_VERSION=$(echo $VERSION | cut -d '.' -f 1-2)
           echo "::set-output name=version::$MAJOR_MINOR_VERSION"
-          echo "Uploading browser libraries for version v$MAJOR_MINOR_VERSION"
+          echo "Uploading bundles for version v$MAJOR_MINOR_VERSION"
 
-      - name: Upload Browser Build Files
+      - name: Upload Bundles to GCS
         run: |
           VERSION=${{ steps.extract-version.outputs.version }}
-          gsutil -m cp -r $GITHUB_WORKSPACE/lib/browser/* gs://${{ secrets.GCS_BUCKET_NAME }}/lib/js/v${VERSION}/
+          gsutil -m cp -r $GITHUB_WORKSPACE/lib/bundles/* gs://${{ secrets.GCS_BUCKET_NAME }}/lib/js/v${VERSION}/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,11 +2,13 @@
 
 ## [v1.4.0](https://github.com/WunderbarNetwork/mini-digital-sdk-js/compare/v1.3.1...v1.3.2) (2023-07-26)
 
+⚠️ Bundle location and file names have been modified, and ESM/UMD/CJS bundles now sit in the `lib/bundles` folder.
+
 Added:
 
 - Added the CHANGELOG.md file
 - Dev: Greatly expanded the test coverage
-- Dev: GitHub action which uploads browser builds to the Mini Digital CDN
+- Dev: GitHub action which uploads bundles to the Mini Digital CDN
 - Dev: CI/Build runs on all supported Node versions - 16 (LTS), 18 (LTS) & 20 (latest)
 
 Fixed:

diff --git a/README.md b/README.md
@@ -2,11 +2,13 @@
 
 [![CI](https://github.com/WunderbarNetwork/mini-digital-sdk-js/actions/workflows/ci.yaml/badge.svg)](https://github.com/WunderbarNetwork/mini-digital-sdk-js/actions/workflows/ci.yaml)
 
-Library that provides an interface to capture analytics events, and send them to [Mini Digital](https://mini.digital). This library can be used in either Node.js or browser-based TypeScript/JavaScript implementations (including frameworks like React or Vue).
+Library that provides an interface to capture analytics events, and send them to [Mini Digital](https://mini.digital). This library can be used in either Node.js or browser-based TypeScript/JavaScript projects (including frameworks like React or Vue).
+
+The SDK is natively built using TypeScript and the ESM module format, and it compiles to the `ES2022` target. There is also backwards CommonJS compatibility provided.
 
 ## Installation
 
-To install the library, you can use npm or yarn. Run the following command:
+To install the SDK, you can use npm or yarn. Run the following command:
 
 ```shell
 npm install @wunderbar-network/mini-digital-sdk
@@ -18,9 +20,9 @@ or
 yarn add @wunderbar-network/mini-digital-sdk
 ```
 
-### Usage
+## Usage
 
-To send a quick event using the Mini Digital SDK, do the following:
+To send a quick Web (front-end) event using the Mini Digital SDK, do the following (TypeScript/ESM syntax):
 
 ```ts
 // Import the library
@@ -38,15 +40,83 @@ const event: AnalyticsEvent = {
 EventTrackingService.postEvent(event);
 ```
 
-See our API reference to get a deeper understanding of the event schema.
+See our API reference to get a deeper understanding of the event schema, and how to send events from different platforms (back-end, mobile, etc).
+
+Sending events to the production endpoint assumes you have already created your project during the Mini Digital App onboarding process. You can always send events to the Mini Digital Event Sink / Sandbox running locally.
+
+## Using bundles inside pure HTML & JavaScript
+
+When not using a package manager (such as npm or yarn), bundles for different module formats can also be directly referenced in client side code (within a `<script>` tag, or in a separate script file). They can be obtained either from the **Mini Digital CDN**, or be found in the `lib/bundles` folder by manually building this project.
+
+Mini Digital provides bundles in two module formats that can be used inside client-side code:
+
+1. **mini-digital-sdk.min.mjs** - ES2015 Modules/ESM bundle for most modern browsers
+2. **mini-digital-sdk.min.umd.js** - Universal Module Definition/UMD bundle, primarily intended for older browsers or other environments
+
+When referencing bundles from the **Mini Digital CDN**, the CDN URL is as follows:
+
+```text
+https://cdn.mini.digital/lib/js/v1.4/mini-digital-sdk.min.mjs
+```
+
+The **version** in the CDN URL above is in the format **`v**#MAJOR**.**#MINOR`** and will always give the latest published **revision**. Released versions can be seen on our [GitHub releases page](https://github.com/WunderbarNetwork/mini-digital-sdk-js/releases).
+
+All of the bundles are minified (hence the `.min` in the file names), and source maps (attaching `.map` to the end of the file name) are also available.
+
+Note: The SDK also provides a third module format (CommonJS/CJS), called `mini-digital-sdk.min.cjs` (and it is also available either via the CDN or from the `lib/bundles` folder). This bundle is primarily intended for backwards compatibility with older Node.js projects (using the `require` rather than `import` syntax), and cannot be used within Web Browsers without previously being converted to a "browser-friendly" version using tools such as webpack or browserify.
+
+### Using the ES2015 Modules/ESM bundle
+
+The ESM bundle is recommended to be used whenever possible, as most modern browsers on desktop and mobile will come with ESM support. To reference the ESM bundle version of the SDK from the **Mini Digital CDN** and send an event, do the following:
 
-### Browser builds
+```html
+<button type="button" id="myButton">Send Interaction Event</button>
 
-If you want a browser-friendly build to use directly into your HTML code, browser builds (CJS/ESM/UMD) can be found in the `lib/browser` folder.
+<script type="module">
+  // Import the ESM-compatible library from the CDN
+  import { EventTrackingService } from "https://cdn.mini.digital/lib/js/v1.4/mini-digital-sdk.min.mjs";
+
+  document.getElementById("myButton").addEventListener("click", () => {
+    EventTrackingService.postEvent({
+      eventName: "button_clicked",
+      eventCategory: "interaction_event",
+      eventSource: "MyHtmlPage.Button",
+      anonymousUser: true,
+    });
+  });
+</script>
+```
+
+### Using the Universal Module Definition/UMD bundle
+
+For older browsers, a UMD version of the bundle can also be used. To send the same event as above,
+while also referencing the UMD bundle version of the SDK from the **Mini Digital CDN**, do the following:
+
+```html
+<button type="button" id="myButton">Send Interaction Event</button>
+
+<!-- Import the UMD-compatible library from the CDN -->
+<script type="text/javascript" src="https://cdn.mini.digital/lib/js/v1.4/mini-digital-sdk.min.umd.js" defer onload="afterLibraryLoaded()"></script>
+
+<script type="text/javascript">
+  // Function to execute after the UMD library has loaded
+  function afterLibraryLoaded() {
+    document.getElementById("myButton").addEventListener("click", () => {
+      // The Mini Digital SDK "lives" in the global `window.MiniDigital` object
+      window.MiniDigital.EventTrackingService.postEvent({
+        eventName: "button_clicked",
+        eventCategory: "interaction_event",
+        eventSource: "MyHtmlPage.Button",
+        anonymousUser: true,
+      });
+    });
+  }
+</script>
+```
 
-### Config
+## Config
 
-By default, the config is set to send events to the production Mini Digital endpoint. If you wish to override the default Mini Digital URL (to point to e.g. a testing instance), you can do so by overriding the config namespace variable:
+By default, the config is set to send events to the production Mini Digital endpoint. If you wish to override the default Mini Digital URL (to point to e.g. a local testing instance), you can do so by overriding the config namespace variable:
 
 ```ts
 import { EventTrackingConfig } from "@wunderbar-network/mini-digital-sdk";
@@ -55,7 +125,7 @@ import { EventTrackingConfig } from "@wunderbar-network/mini-digital-sdk";
 EventTrackingConfig.miniDigitalUrl = "http://localhost:3333/";
 ```
 
-You can also choose to _pause_ sending events (e.g. in your test suites), or not use cookies (to store anonymous tracking IDs):
+You can also choose to _pause_ sending events (e.g. in your test suites/CI builds), or not use cookies (to store anonymous tracking IDs):
 
 ```ts
 import { EventTrackingConfig } from "@wunderbar-network/mini-digital-sdk";

diff --git a/package.json b/package.json
@@ -3,27 +3,38 @@
   "version": "1.4.0",
   "description": "SDK for back-end (Node) and front-end (TypeScript/JavaScript) applications, to send analytics events to Mini.Digital",
   "private": false,
+  "type": "module",
+  "types": "lib/node/types/index.d.ts",
+  "main": "lib/bundles/mini-digital-sdk.min.cjs",
+  "module": "lib/node/index.mjs",
+  "browser": "lib/bundles/mini-digital-sdk.min.umd.js",
   "exports": {
     ".": {
+      "import": "./lib/node/index.mjs",
+      "require": "./lib/bundles/mini-digital-sdk.min.cjs",
       "types": "./lib/node/types/index.d.ts",
-      "import": "./lib/node/index.mjs"
+      "node": "./lib/node/index.mjs",
+      "browser": "./lib/bundles/mini-digital-sdk.min.mjs",
+      "default": "./lib/node/index.mjs"
+    },
+    "./lib/bundles/mini-digital-sdk.min.mjs": {
+      "import": "./lib/bundles/mini-digital-sdk.min.mjs",
+      "types": "./lib/node/types/index.d.ts"
     },
-    "./browser": {
-      "require": "./lib/browser/mini-digital-sdk.cjs.js",
-      "import": "./lib/browser/mini-digital-sdk.esm.js"
+    "./lib/bundles/mini-digital-sdk.min.cjs": {
+      "require": "./lib/bundles/mini-digital-sdk.min.cjs"
+    },
+    "./lib/bundles/mini-digital-sdk.min.umd.js": {
+      "import": "./lib/bundles/mini-digital-sdk.min.umd.js",
+      "types": "./lib/node/types/index.d.ts"
     }
   },
-  "type": "module",
-  "types": "lib/node/types/index.d.ts",
-  "main": "lib/node/index.mjs",
-  "module": "lib/browser/mini-digital-sdk.esm.js",
-  "browser": "lib/browser/mini-digital-sdk.esm.js",
   "scripts": {
     "clean": "rm -rf ./lib",
-    "build": "npm run build:node && npm run build:post && npm run build:browser",
-    "build:node": "npm run clean && tsc --build && mv lib/node/index.js lib/node/index.mjs",
-    "build:browser": "rollup -c",
-    "build:post": "node post-build.js",
+    "build": "run-s clean build:node build:post-node-pre-bundles build:bundles",
+    "build:node": "tsc --build && mv lib/node/index.js lib/node/index.mjs",
+    "build:post-node-pre-bundles": "node post-node-build.js",
+    "build:bundles": "rollup -c",
     "prepare": "npm run build",
     "test": "vitest run",
     "lint": "eslint . --ext .js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --ignore-path .gitignore"
@@ -50,6 +61,7 @@
     "eslint-plugin-promise": "^6.1.1",
     "eslint-plugin-vitest": "^0.2.6",
     "jsdom": "^22.1.0",
+    "npm-run-all": "^4.1.5",
     "prettier": "^3.0.0",
     "rollup": "^3.26.3",
     "typescript": "^5.1.6",
@@ -71,10 +83,11 @@
     "url": "https://github.com/WunderbarNetwork/mini-digital-sdk-js/issues"
   },
   "directories": {
-    "lib": "lib"
+    "lib": "./lib",
+    "test": "./test"
   },
   "files": [
-    "lib/**/*"
+    "./lib/**/*"
   ],
   "contributors": [
     "Miloš Ranđelović <[email protected]>"

diff --git a/post-build.js → post-node-build.js b/post-build.js → post-node-build.js
diff --git a/rollup.config.js b/rollup.config.js
@@ -5,9 +5,9 @@ import terser from "@rollup/plugin-terser";
 export default {
   input: "lib/node/index.mjs", // import compiled TS output
   output: [
-    { name: "miniDigitalSdk", file: "lib/browser/mini-digital-sdk.umd.js", format: "umd", sourcemap: true },
-    { name: "miniDigitalSdk", file: "lib/browser/mini-digital-sdk.cjs.js", format: "cjs", sourcemap: true },
-    { name: "miniDigitalSdk", file: "lib/browser/mini-digital-sdk.esm.js", format: "es", sourcemap: true },
+    { name: "MiniDigital", file: "lib/bundles/mini-digital-sdk.min.umd.js", format: "umd", sourcemap: true },
+    { name: "MiniDigital", file: "lib/bundles/mini-digital-sdk.min.cjs", format: "cjs", sourcemap: true },
+    { name: "MiniDigital", file: "lib/bundles/mini-digital-sdk.min.mjs", format: "es", sourcemap: true },
   ],
   plugins: [
     resolve(), // include dependencies from node_modules (but not devDependencies)