DDC JS Modules

Javascript module library as an npm package.

• Local development with Docker
• Release New Package Version
• Link Development Version
• Unit Tests
• Configure Modules
  • Configure Standalone Module Files
• Javascript Debugging
  • Examples

Local development with Docker

Dependencies

Docker Desktop

Download and install Docker Desktop from: https://www.docker.com/products/docker-desktop/

On Windows use the WSL 2 backend.

Earthly

• macOS:

  brew install earthly/earthly/earthly && earthly bootstrap

• Windows (inside WSL):

  sudo /bin/sh -c 'wget https://github.com/earthly/earthly/releases/latest/download/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly && /usr/local/bin/earthly bootstrap --with-autocomplete'

For more details: https://earthly.dev/get-earthly

Running npm commands

To run npm commands:

docker-compose run --rm npm <npm options>

e.g.:

docker-compose run --rm npm install --save-dev stylelint

Running CI tests locally

To run the complete set of CI tests:

earthly +test

You can also specify a single test to run. e.g.:

earthly +jshint
earthly +mocha

Cleaning up

To clean up the project root (node_modules, ...):

earthly +clean

Release New Package Version

The CI/CD pipeline will automatically bump the package version and publish the new release to npmjs.com if the Pull Request has one of the following labels:

• release:major (Bump the major version number e.g. from 1.8.1 to 2.0.0)
• release:minor (Bump the minor version number e.g. from 1.8.1 to 1.9.0)
• release:patch (Bump the patch version number e.g. from 1.8.1 to 1.8.2)

After the workflow has finished running, you can update the dependency in your project by running npm install '@drugscom/ddcjsmodules@<new version>' in your project root. E.g.:

cd ~/dev/ddcwww
npm install '@drugscom/[email protected]'

Manual mode

Note: The production staging process depends on the creation of a new project tag to get the latest version of the ddcjsmodules project.

Step 1: Create new tag (version) for ddcjsmodules

Ensure all changes have been committed (and tested). Use the command npm version patch to create a new "patch" version. (e.g. 7.17.11 → 7.17.12). Alternatively, replace patch with minor or major to increment the "minor" (7.17.11 → 7.18.0) or "major" (7.17.11 → 8.0.0) versions, if required.

[ddcjsmodules]# git status
[ddcjsmodules]# npm version patch

Push this tag change to GitHub and run npm publish to notify npmjs.com of this new version.

[ddcjsmodules]# git push --tags origin master
[ddcjsmodules]# npm publish

Enter the one-time password from your authenticator app when prompted.

Step 2: Update ddcwww

Edit the package.json file inside the ddcwww project and update the @drugscom/ddcjsmodules dependency with the new tag version created in Step 1.

"dependencies": {
   "@babel/core": "7.14.5",
   "@babel/preset-env": "7.14.5",
   "@drugscom/ddcjsmodules": "7.17.12", <-- New version here
   "autoprefixer": "9.8.6",
   ...
}

From the ddcwww project root, run npm install:

[ddcwww]# npm install

This will use the package.json file to install the specified version of ddcjsmodules into the /node_modules directory, updating the project's package-lock.json file in the process. Changes from both package.json and package-lock.json must be committed/pushed to GitHub.

Link Development Version

Any project can be set up to reference a "live" version of the ddcjsmodules project (versus using the package.json version). This can be very useful in a development environment.

1. Define the ddcjsmodules project as a "node modules link". Note: This only needs to be done once, anytime after cloning.

[home]# git clone [email protected]:drugscom/ddcjsmodules.git
[home]# cd ddcjsmodules/
[ddcjsmodules]# npm install
[ddcjsmodules]# npm link

2. Inside the root directory of the ddcwww project, use the npm link command to link the "live" version of ddcjsmodules set up in Step 1:

[ddcwww]# npm link @drugscom/ddcjsmodules

Note: Running npm install or npm update will break the link, reverting ddcwww to use the package.json version:

[ddcwww]# npm install
- or -
[ddcwww]# npm install @drugscom/ddcjsmodules
- or -
[ddcwww]# npm update @drugscom/ddcjsmodules

Simply repeat Step 2 to recreate the link once again.

Unit Tests

To run all unit tests from the command line:

[ddcjsmodules]# npm test

To run a specific unit test:

[ddcjsmodules]# npm test test/helper.js 

Configure Modules

To use a ddcjsmodules module inside the ddcwww project, the module path will should be aliased inside the browser section of the package.json file:

"browser": {
   "ddc-agent": "./node_modules/@drugscom/ddcjsmodules/src/agent",
   "ddc-analytics": "./node_modules/@drugscom/ddcjsmodules/src/analytics",
   "ddc-config": "./node_modules/@drugscom/ddcjsmodules/src/config",
   "ddc-debug": "./node_modules/@drugscom/ddcjsmodules/src/debug",
   "ddc-error": "./node_modules/@drugscom/ddcjsmodules/src/error",
   "ddc-helper": "./node_modules/@drugscom/ddcjsmodules/src/helper",
   "ddc-timing": "./node_modules/@drugscom/ddcjsmodules/src/timing",
   ...
}

Then the module path can be referenced inside a Javascript file using the require statement:

const Debug = require('ddc-debug');
Debug.log("API response:", data);

const Analytics = require('ddc-analytics');
Analytics.sendEvent({event: 'AdClick', drugName: 'Lexapro'});

Javascript Debugging

Return the current debug configuration (JSON string):

> DDC.Debug.get();

Set the current debug configuration (overrides any existing configuration):

> DDC.Debug.set({options});

The {options} parameter should follow this structure:

{
   show: ['DDC.Class.method', 'DDC.Class2.method2', ...], // Array of strings;
   mark: ['DDC.Class.method', ...]  // Array of strings;
}

Console logging the Debug.trace data will use the logic:

1. if the trace method name starts with a value in the [mark] array, log to console (important color)
2. if the trace method name starts with a value in the [show] array, log to console (standard color)
3. else, do not log

Examples

Use your browser's Developer Tools Console to enter the following commands.

Show all debugging:

> DDC.Debug.set({show: ['']})

Show debugging for methods starting with "Mednotes.Page":

> DDC.Debug.set({show: ['Mednotes.Page']})

Show debugging for methods starting with "DDC.Ads" and "DDC.Page"; highlight methods starting with "DDC.Ads.buildAd":

> DDC.Debug.set({show: ['DDC.Ads', 'DDC.Page'], mark: ['DDC.Ads.buildAd']})

Stop all debugging:

> DDC.Debug.set({show: [], mark: []})