Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View NodeJS on the plugin site for more information.

Provides Jenkins integration for NodeJS & npm packages.

Download & Installation

You can download the latest .hpi and install it from the Manage Plugins menu, or install this plugin directly from the Plugins Update Center.

Main features

  • Provides NodeJS auto-installer, allowing to create as many NodeJS installations "profiles" as you want.
    The auto-installer will automatically install a given version of NodeJS, on every jenkins slave where it will be needed
  • Allows to install globally some npm packages inside each installations, these npm packages will be made available to the PATH
  • Allows to execute some NodeJS script, under a given NodeJS installation
  • Allows use custom NPM user configuration file defined with config-file-provider plugin to setup custom NPM settings
  • Add a lightweight support to DSL pipeline
  • Force 32bit architecture
  • Relocate npm cache folder using pre defined streategies

Usage

  1. After installing the plugin, go to the global jenkins configuration panel (JENKINS_URL/configure or JENKINS_URL/configureTools if using jenkins 2),
    and add new NodeJS installations.
  2. For every Nodejs installation, you can choose to install some global npm packages.
    Since 1.2.6 you could force the installation of the 32bit package for the underlying architecture if supported. If the package is not available the build will fail.

    Note that you might provide npm package's version (with syntax "package@0.1.2" for instance, or maybe better, "package@~0.1.0") in order to enforce
    reproductibility of your npm execution environnment (the ~ syntax allows to benefits from bugfixes without taking the risk of a major version upgrade)
    See below:
  3. Now, go to a job configuration screen, you will have 2 new items :
    • On the "Build environnment" section, you will be able to pick one of the NodeJS installations to provide its bin/ folder to the PATH.
      This way, during shell build scripts, you will have some npm executables available to the command line (like bower or grunt)
      See below:
    • On the "Build" section, you will be able to add a "Execute NodeJS script" build step

      This way, you will be able to fill a textarea with the script content you want to execute.
      Note that you will have to select a NodeJS runtime you previously installed, to specify the NodeJS version you want to use
      during your NodeJS script execution.
  4. You can customise any NPM settings you need creating a NPM config file where you can also setup multiple npm registry (scoped or public)
    and select for each one stored credential (only user/password supported type) as follow:

    and than select the config file to use for each configured build step
  5. You would relocate the npm cache folder to swipe out it when a job is removed or workspace folder is deleted. There are three default strategy:
    • per node, that is the default NPM behavour. All download package are placed in the ~/.npm on Unix system or %APP_DATA%\npm-cache on Windows system;
    • per executor, where each executor has an own NPM cache folder placed in ~/npm-cache/$executorNumber;
    • per job, placed in the workspace folder under $WORKSPACE/npm-cache. This cache will be swipe out together the workspace and will be removed when the job is deleted.

Pipeline

The current supported DSL steps are:

  • nodejs (as buildwrapper)
  • tools

In a Declarative pipeline you can add any configured NodeJS tool to your job, and it will enhance
the PATH variable with the selected NodeJS installation folder, instead in scripted pipeline you have to do it manually.

Example of use tools in Jenkinsfile (Scripted Pipeline)
node {
    env.NODEJS_HOME = "${tool 'Node 6.x'}"
	// on linux / mac
	env.PATH="${env.NODEJS_HOME}/bin:${env.PATH}"
	// on windows
	env.PATH="${env.NODEJS_HOME};${env.PATH}"
	sh 'npm --version'
}

This example show the use of buildwrapper, where enhanced PATH will be available only inside the brace block

Example of the use of buildwrapper Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                nodejs(nodeJSInstallationName: 'Node 6.x', configId: '<config-file-provider-id>') {
                    sh 'npm config ls'
                }
            }
        }
    }
}

Known limitations / issues

NodeJS version 1.0 has adapted its code to the most recent Jenkins API (1.6xx). If also EnvInject is installed you will fall in JENKINS-26583
that corrupts setup of the nodejs installation bin folder into PATH environment. In this case consider if update or not or use an own build from
this branch untill the JENKINS-26583 will not be fixed.

  • If you update from NodeJS 0.2.2 or earlier to newer version materializes a data migration. This data migration is transparent to the users but
    you can not back to 0.2.2 without lost global configuration tools and job build step configuration.
  • NodeJS versions prior to 0.9.0 won't be available at the moment (directory structure was not the same as today on distribution site).
    This might be handled in the future (this is exposed as PathResolver implementation) :
    don't hesitate to provide new implementations for previous versions and submit a PR on github.
  • Supported architecture are:
    • Windows 32/64 bit
    • Linux 32/64 bit
    • OSX (intel) 64 bit
    • Arm 6l/7l/64
    • SunOS

Releases Notes

Moved to github repository page

  • No labels

17 Comments

  1. Unknown User (intel352)

    Several tickets exist around NodeJS plugin mangling PATH vars, conflicting w/ rbenv/RVM plugins. Please address.

  2. Unknown User (sigian80)

    There is a compatibility problem with simultaneous use of MySQL Job Database Plugin (0.1.0) and NodeJS Plugin (0.2.1) in the "Build Environment" definition of a Jenkins job.

    The environment, where job runs, is a Jenkins master (core version:1.565) on Ubuntu 12.04 with a MySQL installation (5.5.3) and NodeJS installation is 0.10.x (I also used a 0.11.x).

    Below there is the log of the build that fails for a "bash: mysql: command not found" error. If Jenkins doesn't find a NodeJS installation, it tries to perform a NodeJS installation and then uses MySQL Job Database plugin to create a mysql database. The issue could be about the path that MySQL Job Database uses to run bash commands, maybe it could be modified by NodeJS Plugin before. Obviously, without the use of NodeJS plugin, MySQL Job Database Plugin works correctly. What does NodeJS Plugin do when it tries to install a specific NodeJS?

    Looking for your feedback, thank you in advance,

    Silvio

    Building on master in workspace /var/lib/jenkins/jobs/Testmysql-clone/workspace

    Updating http://163.162.63.177/myproject/trunk/project at revision '2015-02-10T15:52:58.795 +0100'

    At revision 2289

    no change for http://163.162.63.177/myproject/trunk/project since the previous build

    Ensuring MySQL database for job exists

    $ bash -c 'mysql --host='127.0.0.1' --port='3306' --user='jenkins' --password='jenkins' --execute "CREATE DATABASE IF NOT EXISTS test;"'

    MySQL command failed:

    bash: mysql: command not found

    ERROR: null

    [htmlpublisher] Archiving HTML reports...

    [htmlpublisher] Archiving at PROJECT level /var/lib/jenkins/jobs/Testmysql-clone/workspace/project/coverage/lcov-report to /var/lib/jenkins/jobs/Testmysql-clone/htmlreports/Code_Coverage_analysis

    ERROR: Specified HTML directory '/var/lib/jenkins/jobs/Testmysql-clone/workspace/project/coverage/lcov-report' does not exist.

    Drop MySQL database for job if exists

    $ bash -c 'mysql --host='127.0.0.1' --port='3306' --user='jenkins' --password='jenkins' --execute "DROP DATABASE IF EXISTS test;"'

    MySQL command failed:

    bash: mysql: command not found

    Drop MySQL user for job if exists

    $ bash -c 'mysql --host='127.0.0.1' --port='3306' --user='jenkins' --password='jenkins' --execute "REVOKE ALL PRIVILEGES, GRANT OPTION FROM 'jenkinsuser'@'%';"'

    MySQL command failed:

    bash: mysql: command not found

    Finished: FAILURE

  3. Unknown User (tomccabe)

    npm that is installed by this plugin is broken. Any npm action fails as follows:

    module.js:338
        throw err;
              ^
    Error: Cannot find module 'are-we-there-yet'
        at Function.Module._resolveFilename (module.js:336:15)
        at Function.Module._load (module.js:278:25)
        at Module.require (module.js:365:17)
        at require (module.js:384:17)
        at Object.<anonymous> (/Users/xxxxx/.jenkins/tools/jenkins.plugins.nodejs.tools.NodeJSInstallation/.12.6/lib/node_modules/npm/node_modules/npmlog/log.js:2:16)
        at Module._compile (module.js:460:26)
        at Object.Module._extensions..js (module.js:478:10)
        at Module.load (module.js:355:32)
        at Function.Module._load (module.js:310:12)
        at Module.require (module.js:365:17)
    Build step 'Execute shell' marked build as failure
    Finished: FAILURE

    Wasted an entire day on this plugin.

  4. Unknown User (sc_adams)

    I have found some extra steps are needed for installation to windows.

    For either a manual or Jenkins node install these two steps need to be added.

    1. In the windows nodejs install folder add a new folder "bin" and copy in the node.exe

    2. In Manage Jenkins -> Configure -> Shell, set the shell path as

    C:\Windows\system32\cmd.exe

    (or whatever is appropriate).

    Credits to:

    https://issues.jenkins-ci.org/browse/JENKINS-21953

    and

    http://stackoverflow.com/questions/15135771/hudson-on-windows-error-java-io-ioexception-cannot-run-program-sh

  5. Unknown User (clabnet)

    Thank's Samuel, it work fine.

  6. Unknown User (richiewu)

    Sorry, I couldn't find any place to customise any NPM settings in step 4 of Usage, any one can help me?

    Did I missed anything?

  7. Unknown User (nfalco79)

    Unknown User (clabnet) since 1.0 is no more necessary add node binary to the bin folder. Windows is fully supported.

     

    Unknown User (richiewu) You have to create a NPM config file in Manage Jenkins -> Managed Files (config-file-provider plugin)

  8. Unknown User (ronabop)

    Changing the scripted pipeline example, I had to use:
        env.PATH="${env.NODEJS_HOME}/bin/:${env.PATH}"

    ...since my auto-installed tool places the binaries for node and npm at that location (/bin/).

  9. Unknown User (nfalco79)

    yes it is correct, the bin folder of node js depends from S.O.

  10. Unknown User (gk_nonni)

    In the declarative pipeline, the correct format (as Pipeline v2.5) is: 

    pipe {
      agent any
      tools {nodejs "node-version-installed"}
    }
  11. Unknown User (pixman20)

    It appears that though  JENKINS-26583 - Getting issue details... STATUS  was fixed, the workaround given is still required.

    I just updated both the env-inject plugin and the nodejs plugin to the latest versions (2.1.4 and 1.2.4 respectively) and this is still an issue: node is not added to PATH

  12. Unknown User (jg_lgc)

    Is it possible to specify  a config file using tool in a declarative pipeline?

    tools {
      nodejs "installation-name" configFile:"config-file-id"
    }

    The name installation's pre-installed packages may need to go through an authenticated proxy specified in the managed config file.

    1. Unknown User (nfalco79)

      it's not possible use the proxy defined in manage file during installation of pre-installed packages because managed files are wired to the build job and not to Jenkins instance. For example is not possible retrieve managed file defined in a Folder (kind of Jenkins project).

      If you would use an HTTP proxy define the http proxy in the Manage Jenkins page (see JENKINS-29266).

  13. Unknown User (pavelz)

    Hi, our Jenkins is behind corporate proxy. Which proxy settings is used when I add new NodeJS installation?

    Is it possible to install the NodeJS manually?

    Thanks

    1. Unknown User (nfalco79)

      The proxy settings are those defined in Jenkins (third tab of manage plugin page).

      It is possible to provide a manual installation in the same way of other tools, or a custom URL to a zip archive that contains the NodeJS installer

  14. Unknown User (cedriclevasseur)

    Please note that the code in the example is obsolete, reporting a "TypeError: process.pwd is not a function"

    You can use cwd(), instead :

    console.log('build number' + process.env['BUILD_NUMBER']);
    console.log('current directory' + process.cwd());
  15. Unknown User (jcompagner)

    With the latest release of 1.3.0 if you upgrade, make sure the job configuration is saved once else you will get a null pointer (because i guess the "default" new parameter is not there)