Azure Pipelines のために JavaScript をカスタマイズする

Azure Pipelines を使用すると、独自のインフラストラクチャを設定せずに JavaScript アプリをビルドできます。 JavaScript アプリのビルド、テスト、実行に通常使用するツール (npm、Node、Yarn、Gulp など) は、Azure Pipelines の Microsoft ホストテッド エージェントにプレインストールされています。

プレインストールされている Node.js と npm のバージョンについては、「Microsoft ホステッド エージェント」を参照してください。 これらのツールの特定のバージョンを Microsoft ホステッド エージェントにインストールするには、Node Tool インストーラー タスクをプロセスの先頭に追加します。 セルフホステッド エージェントを使用することもできます。

JavaScript を使用した最初のパイプラインを作成するには、「JavaScript クイックスタート」を参照してください。

特定の Node.js バージョンを使用する

Microsoft ホステッド エージェントにまだインストールされていないバージョンの Node.js と npm が必要な場合は、Node Tool インストーラー タスクを使用します。 次のスニペットを azure-pipelines.yml ファイルに追加します。

注意

ホステッド エージェントは定期的に更新されます。このタスクを設定すると、パイプラインが実行されるたびに新しいマイナー バージョンに更新するためにかなりの時間が費やされます。 パイプラインで特定の Node バージョンが必要な場合にのみこのタスクを使用してください。

- task: UseNode@1
  inputs:
    version: '16.x' # replace this value with the version that you need for your project

npm ツールのみを更新するには、ビルド プロセスで npm i -g npm@version-number コマンドを実行します。

複数のノード バージョンを使用する

Node Tool インストーラー タスクを使用して、複数のバージョンの Node にアプリをビルドしてテストできます。

pool:
  vmImage: 'ubuntu-latest'
strategy:
  matrix:
    node_16_x:
      node_version: 16.x
    node_13_x:
      node_version: 18.x

steps:
- task: UseNode@1
  inputs:
    version: $(node_version)

- script: npm install

ビルド エージェントにツールをインストールする

プロジェクトの package.json または package-lock.json ファイルに開発依存関係であるツールがある場合、npm を使用してツールと依存関係をインストールします。 ツールの正確なバージョンは、ビルド エージェントに存在する他のバージョンとは別にプロジェクト内で定義されます。

スクリプトまたは npm タスクを使用します。

スクリプトを使用して package.json と共にインストールする

- script: npm install --only=dev

npm タスクを使用して package.json と共にインストールする

- task: Npm@1
  inputs:
     command: 'install'

このようにインストールされたツールを実行するには、npm npx パッケージ ランナーを使用します。これは、パスの解決で、このようにインストールされたツールを検出します。 次の例は、mocha テスト ランナーを呼び出しますが、グローバルにインストールされたバージョン (npm install -g を使用) を使用する前に、開発依存関係としてインストールされたバージョンを探します。

- script: npx mocha

プロジェクトに必要だが、package.json で開発依存関係として設定されていないツールをインストールするには、パイプラインの スクリプト ステージから npm install -g を呼び出します。

次の例では、npm を使用して最新バージョンの Angular CLI をインストールします。 こうすると、パイプラインの残りの部分で他の script ステージの ng ツールを使用できます。

注意

Microsoft でホストされる Linux エージェントでは、sudo npm install -g のようにコマンドの前に sudo を付けます。

- script: npm install -g @angular/cli

ヒント

これらのタスクはパイプライン実行のたびに実行されるため、ツールのインストールがビルド時間に与える影響に注意してください。 オーバーヘッドがビルドのパフォーマンスに重大な影響を与える場合は、必要なツールのバージョンを使用してセルフホステッド エージェントを構成することを検討してください。

依存関係の管理

ビルドで、Yarn または Azure Artifacts を使用して、パブリック npm レジストリからパッケージをダウンロードします。 このレジストリは、.npmrc ファイルに指定するプライベート npm レジストリの一種です。

npm を使用する

npm を次のように使用して、ビルドのためにパッケージをダウンロードできます。

• パイプラインで npm install を直接実行します。これは、認証なしでレジストリからパッケージをダウンロードする最も簡単な方法です。 ビルドを実行するためにエージェント上に開発依存関係が必要ない場合は、--only=prod オプションを npm install にすることでビルド時間を短縮できます。
• npm タスクを使用します。 このタスクは、認証済みレジストリを使用している場合に便利です。
• npm 認証タスクを使用します。 このタスクは、タスク ランナー (Gulp、Grunt、Maven) 内から npm install を実行する場合に便利です。

npm レジストリを指定する場合は、リポジトリ内の .npmrc ファイルに URL を配置します。 フィードが認証されたら、[プロジェクト設定] の[サービス] タブで npm サービス接続を作成して、資格情報を管理します。

パイプラインでスクリプトを使用して npm パッケージをインストールするには、次のスニペットを azure-pipelines.yml に追加します。

- script: npm install

.npmrc ファイルで指定されたプライベート レジストリを使用するには、次のスニペットを azure-pipelines.yml に追加します。

- task: Npm@1
  inputs:
    customEndpoint: <Name of npm service connection>

Gulp などのタスク ランナーを介して npm コマンドにレジストリ資格情報を渡すには、タスク ランナーを呼び出す前に、azure-pipelines.yml に次のタスクを追加します。

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

パッケージを npm レジストリから復元するときに接続の問題でビルドが失敗することがある場合は、アップストリーム ソースで Azure Artifacts を使用してパッケージをキャッシュできます。 Azure Artifacts に接続すると、パイプラインの資格情報が自動的に使用されます。 通常、これらの資格情報は、プロジェクト コレクション ビルド サービス アカウントから導出されます。

Microsoft ホステッド エージェントを使用している場合は、ビルドを実行するたびに新しいマシンを取得します。つまり、毎回依存関係が復元されるため、かなりの時間がかかる可能性があります。 軽減するには、Azure Artifacts またはセルフホステッド エージェントを使用してください。パッケージ キャッシュを使用した利点が得られます。

Yarn を使用する

スクリプト ステージを使用して Yarn を呼び出して依存関係を復元します。 Yarn は、一部の Microsoft ホステッド エージェントにプレインストールされています。 これは、他のツールと同様に、セルフホステッド エージェントにインストールして構成できます。

- script: yarn install

JavaScript コンパイラを実行する

Babel や TypeScript tsc コンパイラなどのコンパイラを使用して、ソース コードを Node.js ランタイムまたは Web ブラウザーで使用できるバージョンに変換します。

プロジェクトの package.json ファイルに、コンパイラを実行するスクリプト オブジェクト が設定されている場合は、スクリプト タスクを使用してパイプラインで呼び出します。

- script: npm run compile

スクリプト タスクを使用するとパイプラインからコンパイラを直接呼び出すことができます。 これらのコマンドは、複製されたソース コード リポジトリのルートから実行されます。

- script: tsc --target ES6 --strict true --project tsconfigs/production.json

単体テストを実行する

JavaScript テストを実行するようにパイプラインを構成すると、JUnit XML 形式で書式設定された結果が生成されます。 その後、組み込みのテスト結果の発行タスクを使用して、結果を発行します。

テスト フレームワークで JUnit 出力がサポートされない場合は、mocha-junit-reporter などのパートナー レポート モジュールを通じてサポートを追加します。 JUnit レポーターを使用するようにテスト スクリプトを更新することも、レポーターでコマンド ライン オプションがサポートされる場合は、それらのオプションをタスク定義に渡すこともできます。

次の表に、最もよく使用されるテスト ランナーと、XML 結果の生成に使用できるレポーターを示します。

テスト ランナー	XML レポートを生成するレポーター
mocha	mocha-junit-reporter cypress-multi-reporters
jasmine	jasmine-reporters
jest	jest-junit jest-junit-reporter
karma	karma-junit-reporter
Ava	tap-xunit

次の例では、mocha-junit-reporter を使用し、スクリプトを使用して mocha test を直接呼び出します。 このスクリプトによって、./test-results.xml の既定の場所に JUnit XML 出力が生成されます。

- script: mocha test --reporter mocha-junit-reporter

プロジェクトの package.json ファイルに test スクリプトを定義した場合は、npm test を使用して呼び出すことができます。

- script: npm test

テスト結果を公開する

結果を発行するには、テスト結果の発行タスクを使用します。

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testRunner: JUnit
    testResultsFiles: '**/test-results.xml'

コード カバレッジの結果を発行する

テスト スクリプトによって、Istanbul などのコード カバレッジ ツールが実行される場合は、コード カバレッジ結果の発行タスクを追加します。 このようにすると、ビルドの概要でカバレッジ メトリックを見つけることができ、詳細な分析のために HTML レポートをダウンロードできます。 このタスクでは、Cobertura または JaCoCo レポート出力が必要であるため、適切な出力を生成するために必要なオプションを使用してコード カバレッジ ツールが実行されていることを確認します。 たとえば、「 --report cobertura 」のように入力します。

次の例では、nyc、Istanbul コマンド ライン インターフェイス、および mocha-junit-reporter を使用して、npm test コマンドを呼び出します。

- script: |
    nyc --reporter=cobertura --reporter=html \
    npm test -- --reporter mocha-junit-reporter --reporter-options mochaFile=./test-results.xml
  displayName: 'Build code coverage report'

- task: PublishCodeCoverageResults@2
  inputs: 
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'

ブラウザーのエンド ツー エンド テストを行う

Protractor や Karma などのツールを使用して、ヘッドレス ブラウザーでパイプラインの一部としてテストを実行します。 その後、次のステップでビルドの結果を Azure DevOps に発行します。

1. ヘッドレスの Chrome や Firefox などのヘッドレス ブラウザー テスト ドライバー、または PhantomJS などのブラウザー モック ツールを、ビルド エージェントにインストールします。
2. 選択したヘッドレス ブラウザー/ドライバー オプションを使用するように、ツールのドキュメントに従ってテスト フレームワークを構成します。
3. JUnit 形式のテスト結果を出力するように、テスト フレームワークを構成します (通常はレポーター プラグインまたは構成を使用)。
4. ヘッドレス ブラウザー インスタンスを開始するために必要な CLI コマンドを実行するようにスクリプト タスクを設定します。
5. パイプライン ステージで、単体テストと共にエンド ツー エンドのテストを実行します。
6. 単体テストと同じテスト結果の発行タスクを使用して、結果を発行します。

Web アプリをパッケージ化する

アプリケーションをパッケージ化して、中間出力と依存関係を含めたすべてのアプリケーション モジュールを静的資産にバンドルし、配置に備えます。 コンパイルとテストの後にパイプライン ステージを追加し、Angular CLI を使用して webpack または ng build などのツールを実行します。

最初の例では、webpack を呼び出します。 これが機能するためには、webpack がpackage.json プロジェクト ファイルないで開発依存関係として構成されていることを確認します。 プロジェクトのルート フォルダーに webpack.config.js ファイルがない限り、これによって既定の構成で webpack が実行されます。

- script: webpack

次の例では、npm タスクを使用して npm run build を呼び出して、プロジェクト package.json に定義された build スクリプト オブジェクトを呼び出します。 プロジェクトのスクリプト オブジェクトを使用すると、ビルドのロジックがパイプラインからソース コードに移されます。

- script: npm run build

JavaScript フレームワークを実装する

Angular

Angular アプリの場合、Angular 固有のコマンド (ng test、ng build、ng e2e など) を含めることができます。 パイプラインで Angular CLI コマンドを使用するには、ビルド エージェントに angular/cli npm パッケージをインストールします。

注意

Microsoft でホストされる Linux エージェントでは、sudo npm install -g のようにコマンドの前に sudo を付けます。

- script: |
    npm install -g @angular/cli
    npm install
    ng build --prod

スターター アプリの ng test コマンド (Karma を実行) など、パイプラインでのテストでブラウザーの実行を必要とする場合は、標準ブラウザーの代わりにヘッドレス ブラウザーを使用します。 Angular スターター アプリ:

1. karma.conf.js プロジェクト ファイルの browsers エントリを browsers: ['Chrome'] から browsers: ['ChromeHeadless'] に変更します。

2. karma.conf.js プロジェクト ファイルの singleRun エントリの値を false から true に変更します。 この変更によって、Karma プロセスが実行後に確実に停止します。

React と Vue

React アプリと Vue アプリのすべての依存関係は package.json ファイルにキャプチャされます。 azure-pipelines.yml ファイルには、標準 Node.js スクリプトが含まれます。

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

- script: |
    npm run build
  displayName: 'npm build'

ビルド ファイルは、dist (Vue) または build (React) という新しいフォルダーに含まれます。 このスニペットでは、リリースの準備ができている成果物 - www - をビルドします。 これは、Node インストーラー、ファイルのコピー、およびビルド成果物の発行の各タスクを使用します。

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UseNode@1
  inputs:
    version: '16.x'
  displayName: 'Install Node.js'

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

- script: |
    npm run build
  displayName: 'npm build'

- task: CopyFiles@2
  inputs:
    Contents: 'build/**' # Pull the build directory (React)
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1
  inputs: 
    PathtoPublish: $(Build.ArtifactStagingDirectory) # dist or build files
    ArtifactName: 'www' # output artifact named www

リリースするには、リリース タスクに dist または build 成果物を指定し、Azure Web アプリ配置タスクを使用します。

webpack

webpack 構成ファイルを使用して、コンパイラ (Babel または TypeScript など) を指定し、JSX または TypeScript をプレーン JavaScript にトランスパイルしてアプリをバンドルします。

- script: |
    npm install webpack webpack-cli --save-dev
    npx webpack --config webpack.config.js

ビルド タスク ランナー

通常は、Gulp または Grunt をタスク ランナーとして使用し、JavaScript アプリをビルドしてテストします。

Gulp

Gulp は、Microsoft ホステッド エージェントにプレインストールされています。 YAML ファイルで gulp コマンドを実行します。

- script: gulp                       # include any additional options that are needed

gulpfile.js ファイルのステップで npm レジストリの認証が必要な場合:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: gulp                       # include any additional options that are needed

JUnit または xUnit のテスト結果をサーバーに発行するには、テスト結果の発行タスクを追加します。

- task: PublishTestResults@2
  inputs:
    testResultsFiles: '**/TEST-RESULTS.xml'
    testRunTitle: 'Test results for JavaScript using gulp'

コード カバレッジの結果をサーバーに発行するには、コード カバレッジ結果の発行タスクを追加します。 ビルドの概要でカバレッジ メトリックを見つけることができ、詳細な分析のために HTML レポートをダウンロードできます。

- task: PublishCodeCoverageResults@1
  inputs: 
    codeCoverageTool: Cobertura
    summaryFileLocation: '$(System.DefaultWorkingDirectory)/**/*coverage.xml'
    reportDirectory: '$(System.DefaultWorkingDirectory)/**/coverage'

Grunt

Grunt は、Microsoft ホステッド エージェントにプレインストールされています。 YAML ファイルで grunt コマンドを実行するには:

- script: grunt                      # include any additional options that are needed

Gruntfile.js ファイルのステップで npm レジストリの認証が必要な場合:

- task: npmAuthenticate@0
  inputs:
    customEndpoint: <Name of npm service connection>

- script: grunt                      # include any additional options that are needed

コードをパッケージ化して提供する

アプリのビルドとテストを完了すると、ビルド出力を Azure Pipelines にアップロードして npm または Maven パッケージを作成および発行することも、ビルド出力を .zip ファイルにパッケージ化して Web アプリケーションに配置することもできます。

Azure Pipelines にファイルを発行する

ファイルの作業ディレクトリ全体をアップロードするには、ビルド成果物の発行タスクを使用し、次を azure-pipelines.yml ファイルに追加します。

- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: '$(System.DefaultWorkingDirectory)'

ファイルのサブセットをアップロードするには、最初にファイルのコピー タスクを使用して作業ディレクトリの必要なファイルをステージング ディレクトリにコピーしてから、ビルド成果物の発行タスクを使用します。

- task: CopyFiles@2
  inputs:
    SourceFolder: '$(System.DefaultWorkingDirectory)'
    Contents: |
      **\*.js
      package.json
    TargetFolder: '$(Build.ArtifactStagingDirectory)'

- task: PublishBuildArtifacts@1

npm レジストリにモジュールを発行する

プロジェクトの出力が、Web アプリケーションではなく他のプロジェクトによって使用される npm モジュールである場合は、npm タスクを使用して、モジュールをローカル レジストリまたはパブリック npm レジストリに発行します。 発行するたびに名前とバージョンの一意の組み合わせを指定します。

例

最初の例では、バージョン管理で、package.json ファイルに対する変更を通じて、バージョン情報 (npm バージョンなど) を管理すると仮定しています。 次の例では、スクリプト タスクを使用してパブリック レジストリに発行します。

- script: npm publish

次の例では、リポジトリの .npmrc ファイルで定義されているカスタム レジストリに発行します。 認証資格情報をビルドの実行時に接続時に挿入するように、npm サービス接続を設定します。

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useExternalRegistry
     publishEndpoint: https://my.npmregistry.com

最後の例では、モジュールを Azure DevOps Services パッケージ管理フィードに発行します。

- task: Npm@1
  inputs:
     command: publish
     publishRegistry: useFeed
     publishFeed: https://my.npmregistry.com

npm パッケージのバージョン管理と発行の詳細については、「npm パッケージを発行する」および「ビルド プロセスの一環として npm パッケージをバージョン管理するにはどうすればよいですか?」を参照してください。

Web アプリをデプロイする

Web アプリに発行する準備ができている .zip ファイルを作成するには、ファイルのアーカイブ タスクを使用します。

- task: ArchiveFiles@2
  inputs:
    rootFolderOrFile: '$(System.DefaultWorkingDirectory)'
    includeRootFolder: false

このアーカイブを Web アプリに発行するには、「Azure Web アプリの配置」を参照してください。

イメージをビルドしてコンテナー レジストリにプッシュする

ソース コードが正常にビルドされ、単体テストが正常に配置されると、イメージをビルドしてコンテナー レジストリにプッシュすることもできます。

トラブルシューティング

開発マシンではプロジェクトをビルドできるが、Azure Pipelines でビルドする際に問題が発生する場合は、次の潜在的な原因と是正措置を調べてください。

• 開発マシンの Node.js とタスク ランナーのバージョンが、エージェントのものと一致することを確認します。 node --version のようなコマンド ライン スクリプトをパイプラインに含めると、エージェントに何がインストールされているかを調べることができます。 Node Tool インストーラー (このガイダンスの説明に従って) を使用して、エージェントに同じバージョンを配置するか、npm install コマンドを実行してツールを目的のバージョンに更新します。

• パッケージの復元中にビルドが断続的に失敗する場合は、npm レジストリに問題があるか、Azure データ センターとレジストリの間にネットワークの問題があります。 これらの要因は制御できません。 npm レジストリを含む Azure Artifacts をアップストリーム ソースとして使用することで、ビルドの信頼性が向上するかどうかを調べます。

• nvm を使用して Node.js のさまざまなバージョンを管理している場合は、Node Tool インストーラー タスクへの切り替えを考慮してください。 (nvm は履歴上の理由で macOS イメージにインストールされます。) nvm は、シェル別名を追加して PATH を変更することで複数の Node.js バージョンを管理しますが、Azure Pipelines が各タスクを新しいプロセスで実行する方法との連携がよくありません。

  Node Tool インストーラー タスクではこのモデルが正しく処理されます。 ただし、作業で nvm の使用が必要な場合は、次のスクリプトを各パイプラインの先頭に追加できます。

  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"
  

  その後、node および他のコマンドライン ツールが、パイプライン ジョブの残りの部分で機能します。 nvm コマンドを使用する各ステップで、次のコードを使用してスクリプトを開始します。

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

よく寄せられる質問

Q: Azure Artifacts と Package Management サービスの詳細はどこで確認できますか?

A: Azure Artifacts の Package Management

Q: タスクの詳細はどこで確認できますか?

A: タスクのビルド、リリース、テスト

Q: "致命的なエラー: CALL_AND_RETRY_LAST割り当てに失敗しました - JavaScript ヒープがメモリ不足です" というメッセージでパイプラインが失敗する場合、どのようにして修正すればよいですか?

A: このエラーの種類は、Node.js パッケージがメモリ使用量の制限を超えた場合に発生します。 この問題を解決するには、NODE_OPTIONS のような変数を追加し、--max_old_space_size=16384 という値を割り当てます。

Q: ビルド プロセスの一環として npm パッケージをバージョン管理するにはどうすればよいですか?

A: 1 つのオプションは、バージョン管理と npm バージョンを組み合わせて使用することです。 パイプライン実行の最後に、新しいバージョンでリポジトリを更新できます。 この YAML では、GitHub リポジトリがあり、パッケージが npmjs に配置されます。 npmjs と package.json ファイルでパッケージ バージョンが一致しない場合、ビルドは失敗します。

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