Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

NPM: Difference between revisions

From MoodleDocs
m (Text replacement - "</code>" to "</syntaxhighlight>")
 
(12 intermediate revisions by 2 users not shown)
Line 6: Line 6:


=== npm shrinkwrap ===
=== npm shrinkwrap ===
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run `npm install`. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5. Also note that some changes in node itself can cause changes to the npm-shrinkwrap.json file, for this reason it is recommend that you use the latest stable version of node (8.7 at the moment) when running `npm install`.
We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run `npm install`. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5. Also note that some changes in node itself can cause changes to the npm-shrinkwrap.json file, for this reason it is recommend that you use the latest lts version of node when running `npm install`. See below for more information about versions.


=== Updating npm dependencies ===
=== Updating npm dependencies ===
Periodically we will update our npm dependencies, the process for doing this is:
Periodically we will update our npm dependencies, the process for doing this is:


# Ensure you use npm >= 5 - node version 8 (see MDL-59094 for details of why we require this version)
# Ensure that you have the correct version of NPM/Node installed...
# Run <pre>npm install packages-name@version</pre> (e.g. <pre>npm install eslint@3.8.0</pre>)
## If you are using NVM, then you can (since Moodle 3.5) just run <syntaxhighlight lang="php">nvm use</syntaxhighlight>
# Verify that both the package.json and npm-shrinkwrap.json have been updated
## If you are not... go and install NVM and the run step 1.1 (or install the current version, {{NodeJSVersion}}).
# Commit to source control
# Perform the required changes to the package.json file. Normally.
# Remove the npm-shrinkwrap.json file that is going to be regenerated. <syntaxhighlight lang="php">rm npm-shrinkwrap.json</syntaxhighlight>
# Remove completely the node_modules directory. <syntaxhighlight lang="php">rm -fr node_modules</syntaxhighlight>
# Clean all npm caches. <syntaxhighlight lang="php">npm cache clear --force</syntaxhighlight>
# Run <syntaxhighlight lang="php">npm install</syntaxhighlight>, all packages will be installed.
# Run <syntaxhighlight lang="php">npm shrinkwrap</syntaxhighlight>, a new npm-shrinkwrap.json will be regenerated
# Check that the npm-shrinkwrap.json changes match the modifications performed in the package.json file.
# Verify that grunt, behat tests... do continue working ok.
# Done, you can send the changes for review, integration and, if everything goes ok, will be applied upstream without problem.


=== NPM versions ===
=== NPM versions ===


In general, you will get the best results when using the latest stable NPM version for install node dependencies with Moodle.
In general, you will need to use the latest LTS version available, more exactly {{NodeJSVersion}}


==== Switching NPM versions ====
==== Switching NPM versions ====
We have discovered upstream npm bugs  (MDL-59103) when upgrading NPM version with a previously installed node_modules directory. It is recommended to clear the node_modules directory and re-running `npm install` when changing npm version to avoid these problems. Sometimes it is required to clear the node modules cache as well (do this if you see errors about mis-matching hashes). To clear the node modules cache run "npm cache clear --force".
We have discovered upstream npm bugs  (MDL-59103, MDL-63346) when upgrading NPM version with a previously installed node_modules directory. It is recommended to clear the node_modules directory and re-running `npm install` when changing npm version to avoid these problems. Sometimes it is required to clear the node modules cache as well (do this if you see errors about mis-matching hashes). To clear the node modules cache run "npm cache clear --force".

Latest revision as of 13:05, 14 July 2021

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

NPM is a package manager for JavaScript. It is used by Moodle developers to install a number of cli tools, primarily those related with Grunt.

npm dependency management

Tools installed by npm include things like our css/js compressors, post-processors and integrity checks. As differences in output from these tools would cause different results for different developers working on the same code, we need to ensure installed packages are the same.

npm shrinkwrap

We use a npm-shrinkwrap.json to ensure that all versions of packages are consistent for developers when they run `npm install`. See https://docs.npmjs.com/files/package-locks for further details on this mechanism. Note: The npm package lock mechanics changed significantly in NPM version 5. Also note that some changes in node itself can cause changes to the npm-shrinkwrap.json file, for this reason it is recommend that you use the latest lts version of node when running `npm install`. See below for more information about versions.

Updating npm dependencies

Periodically we will update our npm dependencies, the process for doing this is:

  1. Ensure that you have the correct version of NPM/Node installed...
    1. If you are using NVM, then you can (since Moodle 3.5) just run
      nvm use
      
    2. If you are not... go and install NVM and the run step 1.1 (or install the current version, >=16.14.0 <17 (a.k.a. "lts/gallium"). Right now pointing to nodejs v16.15.1 (see MDL-73915 for more details).).
  2. Perform the required changes to the package.json file. Normally.
  3. Remove the npm-shrinkwrap.json file that is going to be regenerated.
    rm npm-shrinkwrap.json
    
  4. Remove completely the node_modules directory.
    rm -fr node_modules
    
  5. Clean all npm caches.
    npm cache clear --force
    
  6. Run
    npm install
    
    , all packages will be installed.
  7. Run
    npm shrinkwrap
    
    , a new npm-shrinkwrap.json will be regenerated
  8. Check that the npm-shrinkwrap.json changes match the modifications performed in the package.json file.
  9. Verify that grunt, behat tests... do continue working ok.
  10. Done, you can send the changes for review, integration and, if everything goes ok, will be applied upstream without problem.

NPM versions

In general, you will need to use the latest LTS version available, more exactly >=16.14.0 <17 (a.k.a. "lts/gallium"). Right now pointing to nodejs v16.15.1 (see MDL-73915 for more details).

Switching NPM versions

We have discovered upstream npm bugs (MDL-59103, MDL-63346) when upgrading NPM version with a previously installed node_modules directory. It is recommended to clear the node_modules directory and re-running `npm install` when changing npm version to avoid these problems. Sometimes it is required to clear the node modules cache as well (do this if you see errors about mis-matching hashes). To clear the node modules cache run "npm cache clear --force".