Jaa

Customize JavaScript for Azure Pipelines

  • Artikkeli

You can use Azure Pipelines to build your JavaScript apps without having to set up any infrastructure of your own. Tools that you commonly use to build, test, and run JavaScript apps - like npm, Node, Yarn, and Gulp - get pre-installed on Microsoft-hosted agents in Azure Pipelines.

For the version of Node.js and npm that is preinstalled, refer to Microsoft-hosted agents. To install a specific version of these tools on Microsoft-hosted agents, add the Node Tool Installer task to the beginning of your process. You can also use a self-hosted agent.

To create your first pipeline with JavaScript, see the JavaScript quickstart.

Use a specific version of Node.js

If you need a version of Node.js/npm that isn't already installed on the agent:

  1. In the pipeline, select Tasks, choose the phase that runs your build tasks, and then select + to add a new task to that phase.

  2. In the task catalog, find and add the Node Tool Installer task.

  3. Select the task and specify the version of the Node.js runtime that you want to install.

To update just the npm tool, run the npm i -g npm@version-number command in your build process.

Use multiple node versions

You can build and test your app on multiple versions of Node with the Node tool installer task.

See multi-configuration execution.

Install tools on your build agent

Use the npm or command-line tasks in your pipeline to install tools on your build agent.

Manage dependencies

In your build, use Yarn or Azure Artifacts to download packages from the public npm registry. This registry is a type of private npm registry that you specify in the .npmrc file.

Use npm

You can use npm in the following ways to download packages for your build:

  • Directly run npm install in your pipeline, as it's the simplest way to download packages from a registry without authentication. If your build doesn't need development dependencies on the agent to run, you can speed up build times with the --only=prod option to npm install.
  • Use an npm task. This task is useful when you're using an authenticated registry.
  • Use an npm Authenticate task. This task is useful when you run npm install from inside your task runners - Gulp, Grunt, or Maven.

If you want to specify an npm registry, put the URLs in an .npmrc file in your repository. If your feed gets authenticated, create an npm service connection on the Services tab in Project settings to manage its credentials.

Use the npm or npm authenticate task in your pipeline to download and install packages.

If your builds occasionally fail because of connection issues when you restore packages from the npm registry, you can use Azure Artifacts with upstream sources, and cache the packages. The credentials of the pipeline automatically get used when you connect to Azure Artifacts. These credentials are typically derived from the Project Collection Build Service account.

Use Yarn

Use the CLI or Bash task in your pipeline to invoke Yarn.

Run JavaScript compilers

Use the npm task in your pipeline if you have a compile script defined in your project package.json to build the code. Use the Bash task to compile your code if you don't have a separate script defined in your project configuration.

Run unit tests

Use the Publish Test Results and Publish Code Coverage Results tasks in your pipeline to publish test results along with code coverage results by using Istanbul.

Set the Control Options for the Publish Test Results task to run the task even if a previous task has failed, unless the deployment was canceled.

Test browser end-to-end

Run tests in headless browsers as part of your pipeline with tools like Protractor or Karma. Then publish the results for the build to Azure DevOps with the following steps:

  1. Install a headless browser testing driver, such as headless Chrome or Firefox, or a browser-mocking tool such as PhantomJS, on the build agent.
  2. Configure your test framework to use the headless browser/driver option of your choice according to the tool's documentation.
  3. Configure your test framework (usually with a reporter plug-in or configuration) to output JUnit-formatted test results.
  4. Set up a script task to run any CLI commands needed to start the headless browser instances.
  5. Run the end-to-end tests in the pipeline stages along with your unit tests.
  6. Publish the results by using the same Publish Test Results task alongside your unit tests.

Package web apps

Use the CLI or Bash task in your pipeline to invoke your packaging tool, such as webpack or Angular's ng build.

Implement JavaScript frameworks

Angular

For Angular apps, you can include Angular-specific commands such as ng test, ng build, and ng e2e. To use Angular CLI commands in your pipeline, install the angular/cli npm package on the build agent.

Add the following tasks to your pipeline:

  • npm

    • Command: custom
    • Command and arguments: install -g @angular/cli

  • npm

    • Command: install

  • bash

    • Type: inline
    • Script: ng build --prod

For tests in your pipeline that require a browser to run, such as the ng test command in the starter app, which runs Karma, use a headless browser instead of a standard browser. In the Angular starter app:

  1. Change the browsers entry in your karma.conf.js project file from browsers: ['Chrome'] to browsers: ['ChromeHeadless'].

  2. Change the singleRun entry in your karma.conf.js project file from a value of false to true. This change helps make sure that the Karma process stops after it runs.

React and Vue

All the dependencies for your React and Vue apps are captured in your package.json file. Your azure-pipelines.yml file contains the standard Node.js script:

The build files are in a new folder, dist (for Vue) or build (for React). This snippet builds an artifact - www - that is ready for release. It uses the Node Installer, Copy Files, and Publish Build Artifacts tasks.

To release, point your release task to the dist or build artifact and use the Azure Web App Deploy task.

Webpack

You can use a webpack configuration file to specify a compiler, such as Babel or TypeScript, to transpile JSX or TypeScript to plain JavaScript, and to bundle your app.

Add the following tasks to your pipeline:

  • npm

    • Command: custom
    • Command and arguments: install -g webpack webpack-cli --save-dev

  • bash

    • Type: inline
    • Script: npx webpack --config webpack.config.js

Build task runners

It's common to use Gulp or Grunt as a task runner to build and test a JavaScript app.

Gulp

The simplest way to create a pipeline if your app uses Gulp is to use the Node.js with gulp build template when you create the pipeline. This template automatically adds various tasks to invoke Gulp commands and to publish artifacts. In the task, select Enable Code Coverage to enable code coverage by using Istanbul.

Grunt

The simplest way to create a pipeline if your app uses Grunt is to use the Node.js with Grunt build template when you create the pipeline. This automatically adds various tasks to invoke Gulp commands and to publish artifacts. In the task, select the Publish to TFS/Team Services option to publish test results, and select Enable Code Coverage to enable code coverage by using Istanbul.

Package and deliver your code

After you've built and tested your app, you can upload the build output to Azure Pipelines, create and publish an npm or Maven package, or package the build output into a .zip file for deployment to a web application.

Publish artifacts to Azure Pipelines

Use the Publish Build Artifacts task to publish files from your build to Azure Pipelines.

Publish to an npm registry

To create and publish an npm package, use the npm task. For more information about versioning and publishing npm packages, see Publish npm packages.

Deploy a web app

To create a .zip file archive that is ready for publishing to a web app, use the Archive Files task. To publish this archive to a web app, see Azure Web App deployment.

Troubleshoot

If you can build your project on your development machine but are having trouble building it on Azure Pipelines, explore the following potential causes and corrective actions:

  • Check that the versions of Node.js and the task runner on your development machine match those on the agent. You can include command-line scripts such as node --version in your pipeline to check what is installed on the agent. Either use the Node Tool Installer (as explained in this guidance) to deploy the same version on the agent, or run npm install commands to update the tools to wanted versions.

  • If your builds fail intermittently while you restore packages, either the npm registry has issues or there are networking problems between the Azure data center and the registry. We can't control these factors. Explore whether using Azure Artifacts with an npm registry as an upstream source improves the reliability of your builds.

  • If you're using nvm to manage different versions of Node.js, consider switching to the Node Tool Installer task instead. (nvm is installed for historical reasons on the macOS image.) nvm manages multiple Node.js versions by adding shell aliases and altering PATH, which interacts poorly with the way Azure Pipelines runs each task in a new process.

    The Node Tool Installer task handles this model correctly. However, if your work requires the use of nvm, you can add the following script to the beginning of each pipeline:

    steps:
- bash: |
    NODE_VERSION=16  # or whatever your preferred version is
    npm config delete prefix  # avoid a warning
    . ${NVM_DIR}/nvm.sh
    nvm use ${NODE_VERSION}
    nvm alias default ${NODE_VERSION}
    VERSION_PATH="$(nvm_version_path ${NODE_VERSION})"
    echo "##vso[task.prependPath]$VERSION_PATH"

    Then, node and other command-line tools work for the rest of the pipeline job. In each step where you use the nvm command, start the script with the following code:

    - bash: |
    . ${NVM_DIR}/nvm.sh
    nvm <command>

FAQ

Q: Where can I learn more about Azure Artifacts and the Package Management service?

A: Package Management in Azure Artifacts

Q: Where can I learn more about tasks?

A: Build, release, and test tasks

Q: How do I fix a pipeline failure with the message 'FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory'?

A: This failure type happens when the Node.js package exceeds the memory usage limit. To resolve the issue, add a variable like NODE_OPTIONS and assign it a value of --max_old_space_size=16384.

Q: How can I version my npm packages as part of the build process?

A: One option is to use a combination of version control and npm version. At the end of a pipeline run, you can update your repo with the new version. In this YAML, there's a GitHub repo and the package gets deployed to npmjs. Your build fails if there's a mismatch between your package version on npmjs and your package.json file.

variables:
    MAP_NPMTOKEN: $(NPMTOKEN) # Mapping secret var

trigger:
- none

pool:
  vmImage: 'ubuntu-latest'

steps: # Checking out connected repo
- checkout: self
  persistCredentials: true
  clean: true
    
- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc
    customEndpoint: 'my-npm-connection'
    
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

- script: |
    npm install
  displayName: 'npm install'

- script: |
    npm pack
  displayName: 'Package for release'

- bash: | # Grab the package version
    v=`node -p "const p = require('./package.json'); p.version;"`
    echo "##vso[task.setvariable variable=packageVersion]$v"

- task: CopyFiles@2
  inputs:
      contents: '*.tgz'
      targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy archives to artifacts staging directory'

- task: CopyFiles@2
  inputs:
    sourceFolder: '$(Build.SourcesDirectory)'
    contents: 'package.json' 
    targetFolder: $(Build.ArtifactStagingDirectory)/npm
  displayName: 'Copy package.json'

- task: PublishBuildArtifacts@1 
  inputs:
    PathtoPublish: '$(Build.ArtifactStagingDirectory)/npm'
    artifactName: npm
  displayName: 'Publish npm artifact'

- script: |  # Config can be set in .npmrc
    npm config set //registry.npmjs.org/:_authToken=$(MAP_NPMTOKEN) 
    npm config set scope "@myscope"
    # npm config list
    # npm --version
    npm version patch --force
    npm publish --access public

- task: CmdLine@2 # Push changes to GitHub (substitute your repo)
  inputs:
    script: |
      git config --global user.email "username@contoso.com"
      git config --global user.name "Azure Pipeline"
      git add package.json
      git commit -a -m "Test Commit from Azure DevOps"
      git push -u origin HEAD:main