Pipelines för JavaScript-appar

Den här artikeln förklarar hur Azure Pipelines fungerar med JavaScript-appar. Microsoft-värdbaserade agenter förinstallerar vanliga JavaScript-bygg-, test- och distributionsverktyg som npm, Node.js, Yarn och Gulp utan att du behöver konfigurera någon infrastruktur. Du kan också konfigurera lokalt installerade agenter.

Information om hur du snabbt skapar en pipeline för JavaScript finns i Snabbstart för JavaScript.

Installationsprogram för nodverktyg

Så här installerar du Node.js- och npm-versioner som inte är förinstallerade eller för att installera verktygen på lokalt installerade agenter:

• Kör npm i -g npm@version-number-kommandot i din pipeline för npm.
• För Node.jslägger du till uppgiften Använd Node.js ekosystem v1 (UseNode@1) i pipelinen.

- task: UseNode@1
  inputs:
    version: '16.x' # replace with the version you need

Använda flera nodversioner

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

Installation av beroendeverktyg

Om du har verktyg för utvecklingsberoende i projektet package.json eller package-lock.json fil installerar du verktygen och beroendena via npm. Projektfilen definierar den exakta versionen av verktygen, oberoende av andra versioner som finns i byggagenten.

Om du vill installera dessa verktyg på byggagenten använder du ett skript, npm-uppgiften eller en kommandoradsaktivitet i pipelinen.

Så här använder du ett skript:

- script: npm install --only=dev

Så här använder du npm-aktiviteten:

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

Verktyg som du installerar på det här sättet använder npm-paketlöparen npx , som identifierar verktygen i sin PATH-lösning. I följande exempel anropas testlöparen mocha och versionen för utvecklingsberoende används i stället för den version som installeras globalt via npm install -g.

- script: npx mocha

Om du vill installera verktyg som projektet behöver som inte anges som utvecklingsberoenden i package.jsonanropar npm install -g du från ett skript i pipelinen. I följande exempel installeras den senaste versionen av Angular CLI med hjälp npmav . Andra skript i pipelinen kan sedan använda Angular-kommandona ng .

- script: npm install -g @angular/cli

Nedladdningar av beroendepaket

Du kan använda Yarn eller Azure Artifacts för att ladda ned paket från det offentliga npm-registret eller ett privat npm-register som du anger i en *.npmrc-fil . Om du vill ange ett npm-register lägger du till dess URL i filen *.npmrc i kodlagringsplatsen.

Använd npm

Du kan använda npm för att ladda ned byggpaket i pipelinen på följande sätt:

• Det enklaste sättet att ladda ned paket utan autentisering är att du kör npm install direkt.
• Om du vill använda ett autentiserat register lägger du till uppgiften npm.
• Om du vill köra npm install inifrån aktivitetslöparna Gulp, Grunt eller Maven använder du npm-autentisera uppgiften.

Om du vill installera npm-paket direkt använder du följande skript i azure-pipelines.yml. Om din byggagent inte behöver utvecklingsberoenden kan du påskynda byggtiden genom att lägga till --only=prod alternativet i npm install.

- script: npm install --only=prod

Om du vill använda ett privat register som anges i filen *.npmrc lägger du till Npm@1-uppgiften i azure-pipelines.yml.

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

Om du vill skicka registerautentiseringsuppgifter till npm-kommandon via aktivitetslöpare som Gulp lägger du till npmAuthenticate@0 uppgiften i azure-pipelines.yml innan du anropar aktivitetslöparen.

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

Använda Yarn

Använd ett skript för att installera Yarn för att återställa beroenden. Yarn är förinstallerat på vissa agenter som är värdbaserade av Microsoft. Du kan installera och konfigurera Yarn på lokalt installerade agenter som alla andra verktyg.

- script: yarn install

Du kan också använda CLI - eller Bash-uppgiften i pipelinen för att anropa Yarn.

JavaScript-kompilatorer

JavaScript-appar använder kompilatorer som Babel och TypeScript-kompilatorntsc för att konvertera källkod till versioner som kan användas av Node.js-körningen eller i webbläsare. Om du har konfigurerat ett skriptobjekt i projektet package.json fil för att köra kompilatorn kan du anropa det i pipelinen.

- script: npm run compile

Du kan också anropa kompilatorer direkt från pipelinen med hjälp av ett skript. Dessa kommandon körs från roten på den klonade källkodslagringsplatsen.

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

Du kan använda npm-aktiviteten för att skapa koden om projektet package.json definierar ett kompileringsskript. Om du inte definierar ett kompileringsskript kan du använda Bash-aktiviteten för att kompilera koden.

Enhetstestning

Du kan konfigurera dina pipelines för att köra JavaScript-testerna så att de ger resultat i JUnit XML-format. Du kan sedan publicera resultaten med hjälp av uppgiften Publicera testresultat .

Om testramverket inte stöder JUnit-utdata lägger du till stöd via en partnerrapporteringsmodul, till exempel mocha-junit-reporter. Du kan antingen uppdatera testskriptet för att använda JUnit-reportern eller skicka dessa alternativ till uppgiftsdefinitionen om reportern har stöd för kommandoradsalternativ.

I följande tabell visas de vanligaste testlöparna och de reportrar som du kan använda för att skapa XML-resultat:

I följande exempel används mocha-junit-reporter och anropas mocha test direkt med hjälp av ett skript. Det här skriptet genererar JUnit XML-utdata på standardplatsen för ./test-results.xml.

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

Om du har definierat ett test skript i projektet package.json fil kan du anropa det med hjälp npm testav .

- script: npm test

Publicera testresultat

Om du vill publicera testresultat använder du uppgiften Publicera testresultat .

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

Publicera resultat för kodtäckning

Om testskripten kör ett kodtäckningsverktyg som Istanbul lägger du till uppgiften Publicera kodtäckningsresultat . Du kan sedan se täckningsmått i byggsammanfattningen och ladda ned HTML-rapporter för ytterligare analys.

Uppgiften förväntar sig Cobertura- eller JaCoCo-rapporteringsutdata. Se till att kodtäckningsverktyget körs med de alternativ som krävs för att generera rätt utdata, till exempel --report cobertura.

- 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'

Webbläsartestning från slutpunkt till slutpunkt

Din pipeline kan använda verktyg som Protractor eller Karma för att köra tester i huvudlösa webbläsare och sedan publicera testresultat. Följ dessa steg för att konfigurera webbläsartestning och publicera resultat:

1. Installera en huvudlös webbläsartestdrivrutin som headless Chrome eller Firefox, eller ett verktyg för att simulera webbläsare som PhantomJS, på byggagenten.
2. Konfigurera testramverket så att det använder den huvudlösa webbläsaren eller drivrutinsalternativet enligt verktygets dokumentation.
3. Konfigurera testramverket så att JUnit-formaterade testresultat matas ut, vanligtvis med ett reporter-plugin-program eller en konfiguration.
4. Lägg till ett skript eller en CLI-uppgift för att starta huvudlösa webbläsarinstanser.
5. Kör testerna från slutpunkt till slutpunkt i pipelinestegen tillsammans med dina enhetstester.
6. Publicera resultaten tillsammans med enhetstesterna med hjälp av samma uppgift publicera testresultat .

Paketering och leverans

När du har skapat och testat din app kan du:

• Ladda upp byggutdata till Azure Pipelines.
• Skapa och publicera ett npm- eller Maven-paket.
• Paketera byggutdata i ett ZIP-arkiv för distribution till ett webbprogram.

Publicera filer till Azure Pipelines

Om du vill ladda upp hela arbetskatalogen lägger du till uppgiften Publicera byggartefakter i din azure-pipelines.yml-fil .

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

Om du vill ladda upp en delmängd filer kopierar du först de filer som behövs från arbetskatalogen till en mellanlagringskatalog med uppgiften Kopiera filer och använder sedan aktiviteten Publicera byggartefakter .

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

- task: PublishBuildArtifacts@1

Publicera en modul till ett npm-register

Om projektets utdata är en npm modul för andra projekt att använda och inte är ett webbprogram använder du npm-uppgiften för att publicera modulen till ett lokalt register eller till det offentliga npm-registret. Ange en unik kombination av namn/version varje gång du publicerar.

I följande exempel används skriptet för att publicera till det offentliga npm-registret. Exemplet förutsätter att du hanterar versionsinformation som npm-version via en package.json fil i versionskontroll.

- script: npm publish

I följande exempel publiceras till ett anpassat register som definierats i lagringsplatsens *.npmrc-fil. Konfigurera en npm-tjänstanslutning för att mata in autentiseringsuppgifter i anslutningen när bygget körs.

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

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

Mer information om versionshantering och publicering av npm-paket finns i Publicera npm-paket och Hur kan jag version mina npm-paket som en del av byggprocessen.

Paketera och distribuera en webbapp

Du kan paketera program för att paketera alla moduler med mellanliggande utdata och beroenden i statiska tillgångar som är redo för distribution. Lägg till en pipelinefas efter kompilering och testning för att köra ett verktyg som webpack eller Angular CLI ng-versionen.

I följande exempel anropas webpack. För att den här processen ska fungera kontrollerar du att webpack den är konfigurerad som ett utvecklingsberoende i dinpackage.json projektfil. Det här skriptet körs webpack med standardkonfigurationen, såvida du inte har en webpack.config.js fil i rotmappen för projektet.

- script: webpack

I följande exempel används npm run build för att anropa build skriptobjektet som definierats i projektet package.json fil. Om du använder skriptobjektet i projektet flyttas bygglogik till källkoden och ut ur pipelinen.

- script: npm run build

Du kan också använda CLI - eller Bash-uppgiften i pipelinen för att anropa paketeringsverktyget, till exempel webpack eller Angulars ng build.

Om du vill skapa ett *.zip filarkiv som är redo att publicera till en webbapp använder du uppgiften Arkivfiler .

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

Information om hur du publicerar det här arkivet till en webbapp finns i Distribuera till Azure App Service med hjälp av Azure Pipelines.

JavaScript-ramverk

Du kan installera paket i din pipeline för att stödja olika JavaScript-ramverk.

Angular

För Angular-appar kan du köra Angular-specifika kommandon som ng test, ng buildoch ng e2e. Om du vill använda Angular CLI-kommandon i pipelinen installerar du angular/cli npm-paketet på byggagenten.

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

För tester i pipelinen som kräver att en webbläsare körs, till exempel att köra Karma med ng test kommandot, använder du en huvudlös webbläsare i stället för en standardwebbläsare. I Angular-startappen:

• browsers Ändra posten i din karma.conf.js projektfil från browsers: ['Chrome'] till browsers: ['ChromeHeadless'].
• singleRun Ändra posten i din karma.conf.js projektfil från false till true. Den här ändringen hjälper att säkerställa att Karma-processen stoppas direkt efter att den har körts.

React och Vue

Alla beroenden för React- och Vue-appar samlas in i dinpackage.json-fil . Din azure-pipelines.yml-fil innehåller standardskripten npm .

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

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

Byggfilerna finns i en ny mapp, dist för Vue eller build för React. I följande exempel skapas en artefakt, www, som är redo för lansering. Pipelinen använder uppgifterna Använd Node.js, Kopiera fil och Publicera byggartefakter.

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

För att lansera appen, rikta versionsuppgiften mot artefakten dist eller build och använd uppgiften Azure Web App.

Webpack

Du kan använda en webpack-konfigurationsfil för att ange en kompilator, till exempel Babel eller TypeScript, för att transpilera JavaScript XML (JSX) eller TypeScript till oformaterad JavaScript och paketera din app.

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

Skapa aktivitetslöpare

Det är vanligt att använda Gulp eller Grunt som uppgiftslöpare för att skapa och testa JavaScript-appar.

Klunk

- script: gulp # add any needed options

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

- script: gulp

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

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

Grunt

- script: grunt # add any needed options

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

- script: grunt

Felsökning

Om du kan bygga projektet på utvecklingsdatorn men inte kan bygga det i Azure Pipelines kan du utforska följande potentiella orsaker och korrigerande åtgärder.

• Kontrollera att versionerna av Node.js och aktivitetslöparen på utvecklingsdatorn matchar dem i agenten.

  Du kan inkludera kommandoradsskript, till exempel node --version, i din pipeline för att kontrollera vilka versioner som är installerade på agenten. Använd antingen uppgiften Use Node.js för att installera samma version på agenten eller kör npm install kommandon för att uppdatera verktygsversionerna.

• Om dina versioner misslyckas tillfälligt när du återställer paket har npm-registret antingen problem eller så finns det nätverksproblem mellan Azure-datacentret och registret. Utforska om användning av Azure Artifacts med ett npm-register som en överordnad källa förbättrar tillförlitligheten för dina versioner.

• Om du använder nvm för att hantera olika versioner av Node.js, kan du byta till uppgiften Använd Node.js (UseNode@1) i stället. nvm är installerat av historiska skäl på macOS-avbildningen. nvm hanterar flera Node.js versioner genom att lägga till gränssnittsalias och ändra PATH, vilket interagerar dåligt med hur Azure Pipelines kör varje uppgift i en ny process. Mer information finns i Pipelinekörningar.

  Uppgiften Use Node.js hanterar modellen korrekt. Men om ditt arbete kräver att du använder nvmkan du lägga till följande skript i början av varje pipeline:

  steps:
  - bash: |
      NODE_VERSION=16  # or your preferred version
      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 Sedan fungerar andra kommandoradsverktyg för resten av pipelinejobbet. I varje steg där du använder nvm kommandot startar du skriptet med följande kod:

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

Vanliga frågor

Hur åtgärdar jag ett pipelinefel som visar meddelandet "FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed – JavaScript heap out of memory"?

Den här feltypen inträffar när Node.js-paketet överskrider minnesanvändningsgränsen. Lös problemet genom att lägga till en variabel som NODE_OPTIONS och tilldela den värdet --max_old_space_size=16384.

Hur kan jag version mina npm-paket som en del av byggprocessen?

Ett alternativ är att använda en kombination av versionskontroll och npm-version. I slutet av en pipelinekörning kan du uppdatera lagringsplatsen med den nya versionen. Följande YAML-pipeline har en GitHub-lagringsplats och paketet distribueras till npmjs. Bygget misslyckas om det finns ett matchningsfel mellan paketversionen på npmjs och filenpackage.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

Relaterat innehåll

• Mer information om Azure Artifacts och pakethanteringstjänsten finns i Pakethantering i Azure Artifacts.
• Mer information om uppgifter finns i Skapa, släppa och testa uppgifter.