GlobalGiving Living Styleguide

Third-party libraries we want to use have previously been kept in the /v2/js/deps folder.

As of 2018-10 we are moving to using node packages and NPM to manage versions and dependencies. This will be a gradual migration. Meanwhile, libraries in /v2/js/deps will be updated as needed, but no additional libraries will be added.

Moving to NPM resolves some of the outstanding questions around 3rd party libraries.

• A way to document the libraries' functionality, and current maintenance status.
• A simple way to track pages using the libraries by greping for require(). This may generate an automated list in the future.
• A way to upgrade without risking having multiple versions in production, although we will need to be careful about libraries already in /v2/js/deps.
• This approach will simplify minimizing libraries as most packages provide a minimized version or are compatible with minify/uglify.
• Packaged modules should make it easier to concatenate everything into a single minified package without any special cases. This should reduce the number of requests to load a page and may have gzip benefits.

To use:

npm install library-name --save

or for things used only in the build or testing

npm install library-name --save-dev

Then in the Javascript file (*.bsfy) use the library with:

var libraryName = require("library-name");

Versions will be automatically kept and maintained in package.json and package-lock.json. To update to the latest versions run.

npm update

Test thouroughly and commit package.json and package-lock.json.