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:
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
- Check in the file to
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: