How to add a new third party JavaScript library to LMS or Studio

Table of Contents

Install the Library

• Our preference is to install all JavaScript libraries using npm:

  • See if it can be found here: https://www.npmjs.com/

  • If so, update edx-platform's package.json file to reference the library

    • Be sure to use the "~" prefix for the version to allow patches to be picked up automatically

    • For more details about versioning, see: http://semver.org/

  • Execute the following to have your library installed:

    paver install_prereqs

  • Add your new library to the list of NPM-installed libraries:

    • https://github.com/edx/edx-platform/blob/master/pavelib/assets.py#L43

  • Execute the following to have your library available as a Django static asset (choose LMS or Studio or both as appropriate):

    paver update_assets lms --settings=devstack

• Add the new library to the list of vendor libraries that are installed by update_assets:

  • Update the variable NPM_INSTALLED_LIBRARIES here: https://github.com/edx/edx-platform/blob/master/pavelib/assets.py#L47

  • Note: be sure to reference the unminified version of the library. This allows developers to debug into the library, and the Django static asset pipeline will ensure that it get optimized for production.

• If you can't use NPM for some reason, then do the following instead:

  • Check in the file to common/static/vendor

Use the Library

• If the library needs to be used everywhere, register it as a base library:

  • Add to the `lms/env/common.py` at https://github.com/edx/edx-platform/blob/master/lms/envs/common.py#L1246

  • Add to the `lms/static/js/require-config.js` at https://github.com/edx/edx-platform/blob/master/lms/static/lms/js/require-config.js#L51

• If the library is only to be used in a few places, use RequireJS to load it

  • See RequireJS for more details

See Also

• This PR updates a library to use npm so touches most of the relevant files:

  • https://github.com/edx/edx-platform/pull/11963/files