fix(build): Resume UMD bundle build, and restore docs (#152)

spencerwilson-optimizely · web-flow · commit b1d6891f9e75 · 2018-08-20T15:24:25.000-07:00
## Summary - Restore the `build-browser-umd` npm script, which produces dist/optimizely.browser.umd.min.js - Change the UMD lib name `optimizelyClient` -> `optimizelySdk`, since the `createInstance` client factory function may be one of several exports of the SDK, in the future. - (not a visible change) Change Markdown indentation of some bull points, to please my Markdown editor [Typora](https://typora.io/) This undoes one bit of #135. I hadn't realized that this asset _was_ documented, and does have some uses, like faster/easier prototyping in a browser. ## Test plan I made a foo.html with ```html <html> <head> <script src="./dist/optimizely.browser.umd.min.js"></script> <script> console.log('trying sdk'); window.optimizelySdk console.log('trying client'); window.optimizelyClient console.log('trying client'); window.optimizelyClient </script> </head> </html> ``` and it still works: ![screen shot 2018-08-20 at 2 59 47 pm](https://user-images.githubusercontent.com/20175438/44369024-b9d4b580-a489-11e8-9e2b-c8159917b68e.png)
diff --git a/package.json b/package.json
@@ -3,9 +3,10 @@
   "version": "1.0.0",
   "name": "optimizely-sdk-packages",
   "scripts": {
-    "postinstall": "lerna bootstrap",
+    "postinstall": "lerna bootstrap && lerna run build",
+    "build": "lerna run build",
     "clean": "lerna run clean",
-    "publish": "lerna publish",
+    "publish": "npm run build && lerna publish",
     "test": "lerna run test --stream",
     "test-xbrowser": "lerna run test-xbrowser --stream"
   },
diff --git a/packages/optimizely-sdk/CHANGELOG.MD b/packages/optimizely-sdk/CHANGELOG.MD
@@ -1,3 +1,14 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Deprecated
+* The UMD build of the SDK now assigns the SDK namespace object to `window.optimizelySdk` rather than to `window.optimizelyClient`. The old name still works, but on its first access a deprecation warning is logged to the console. The alias will be removed in the 3.0.0 release.
+
 ## 2.1.1
 June 19, 2018
 
diff --git a/packages/optimizely-sdk/README.md b/packages/optimizely-sdk/README.md
@@ -15,13 +15,13 @@ This directory contains the source code for the JavaScript SDK, which is usable
 ### Prerequisites
 
 Ensure the SDK supports all of the platforms you're targeting. In particular, the SDK targets any ES5-compliant JavaScript environment. We officially support:
-  - Node.js >= 4.0.0. By extension, environments like AWS Lambda, Google Cloud Functions, and Auth0 Webtasks are supported as well. Older Node.js releases likely work too (try `npm test` to validate for yourself), but are not formally supported.
-  - [Web browsers](https://caniuse.com/#feat=es5)
+- Node.js >= 4.0.0. By extension, environments like AWS Lambda, Google Cloud Functions, and Auth0 Webtasks are supported as well. Older Node.js releases likely work too (try `npm test` to validate for yourself), but are not formally supported.
+- [Web browsers](https://caniuse.com/#feat=es5)
 
 Other environments likely are compatible, too, but note that we don't officially support them:
-  - Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova.
-  - [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Fly](https://fly.io/), both of which are powered by recent releases of V8.
-  - Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀
+- Progressive Web Apps, WebViews, and hybrid mobile apps like those built with React Native and Apache Cordova.
+- [Cloudflare Workers](https://developers.cloudflare.com/workers/) and [Fly](https://fly.io/), both of which are powered by recent releases of V8.
+- Anywhere else you can think of that might embed a JavaScript engine. The sky is the limit; experiment everywhere! 🚀
 
 Once you've validated that the SDK supports the platforms you're targeting, fetch the package from [NPM](https://www.npmjs.com/package/@optimizely/optimizely-sdk). Using `npm`:
 
@@ -32,6 +32,14 @@ npm install --save @optimizely/optimizely-sdk
 ### Usage
 See the Optimizely X Full Stack [developer documentation](http://developers.optimizely.com/server/reference/index.html) to learn how to set up your first JavaScript project and use the SDK.
 
+The package's entry point is a CommonJS module, which can be used directly in environments which support it (e.g., Node.js, or loaded in a browser via Browserify or RequireJS). Additionally, you can include a standalone bundle of the SDK in your web page by fetching it from [unpkg](https://unpkg.com/):
+
+```html
+<script src="https://unpkg.com/@optimizely/optimizely-sdk/dist/optimizely.browser.umd.js"></script>
+```
+
+When evaluated, that bundle assigns the SDK's exports to `window.optimizelySdk`. If you wish to use the asset locally (for example, if unpkg is down), you can find it in your local copy of the package at dist/optimizely.browser.umd.min.js, or [here in GitHub](./dist/optimizely.browser.umd.min.js).
+
 Regarding `EventDispatcher`s: In Node.js and browser environments, the default `EventDispatcher` is powered by the [`http/s`](https://nodejs.org/api/http.html) modules and by [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest#Browser_compatibility), respectively. In all other environments, you must supply your own `EventDispatcher`.
 
 ### Migrating from 1.x.x
diff --git a/packages/optimizely-sdk/package.json b/packages/optimizely-sdk/package.json
@@ -7,10 +7,11 @@
   "scripts": {
     "test": "mocha ./lib/*.tests.js ./lib/**/*.tests.js ./lib/**/**/*tests.js --recursive",
     "test-xbrowser": "karma start karma.bs.conf.js --single-run",
+    "build-browser-umd": "./scripts/build_browser_umd.sh",
     "lint": "eslint lib/**",
     "cover": "istanbul cover _mocha ./lib/*.tests.js ./lib/**/*.tests.js ./lib/**/**/*tests.js",
     "coveralls": "npm run cover -- --report lcovonly && cat ./coverage/lcov.info | coveralls",
-    "prepublishOnly": "npm test && npm run test-xbrowser"
+    "prepublishOnly": "npm test && npm run test-xbrowser && npm run build-browser-umd"
   },
   "repository": {
     "type": "git",
diff --git a/packages/optimizely-sdk/scripts/build_browser_umd.sh b/packages/optimizely-sdk/scripts/build_browser_umd.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash -e
+
+BUNDLE_NAME="optimizelySdk"
+
+npx webpack -p lib/index.browser.js dist/optimizely.browser.umd.min.js \
+  --output-library-target=umd \
+  --output-library="$BUNDLE_NAME"
+
+# Append some backwards-compatibility code to the bundle
+cat - >> dist/optimizely.browser.umd.min.js <<EOF
+
+
+window._optimizelyClientWarningGiven = false;
+
+Object.defineProperty(window, 'optimizelyClient', {
+  get: function () {
+    if (!window._optimizelyClientWarningGiven) {
+      console.warn('Accessing the SDK via window.optimizelyClient is deprecated; please use window.optimizelySdk instead. This alias will be dropped in 3.0.0.');
+      window._optimizelyClientWarningGiven = true;
+    }
+
+    return {
+      createInstance: window.optimizelySdk.createInstance
+    };
+  }
+});
+EOF
+
