09-Publishing-npm-package.md

🔨 Hands-on: Creating and publishing an npm package

In this hands-on lab you will learn how to publish npm packages to GitHub using GitHub Actions. The module has the following steps:

• Ceating an npm package
• Publishing an npm package
• Automatically setting the NPM version

Ceating an npm package

1. Create a new repository and select Node as your .gitignore template:

   

2. Clone the repository to your local machine or open it in code spaces.

   

   $ git clone <URL>

3. Create a file index.js and add some simple JavaScript code, for example:

   alert("Hello, World!");

4. If you have npm installed on your machine, run npm init and initialize your package using the wizard. Leave the defaults for the other values.

   $ npm init
   ...
   package name: @YOUR-USER/YOUR-REPO
   ...
   test command: exit 0
   ...

   If you don't have npm installed, just clone this repository and copy the files package.json and package-lock.json to you local repo. Adjust the URLs and package name to include your username and repo.

5. Commit and push your files:

   $ git add index.js package.json package-lock.json
   $ git commit -m "Initialize package"
   $ git push

Publishing an npm package

1. Create a file .github/workflows/release-package.yml and copde the following content to it:

   name: Node.js Package
   
   on:
     release:
       types: [created]
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - uses: actions/setup-node@v2
           with:
             node-version: 12
         - run: npm ci
         - run: npm test
   
     publish-gpr:
       needs: build
       runs-on: ubuntu-latest
       permissions:
         packages: write
         contents: read
       steps:
         - uses: actions/checkout@v2
         - uses: actions/setup-node@v2
           with:
             node-version: 12
             registry-url: https://npm.pkg.github.com/
         - run: npm ci
         - run: npm publish
           env:
             NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

2. Create a file .npmrc in the root of your repository with the following content:

   @YOUR-USER:registry=https://npm.pkg.github.com

3. Commit and push the new files:

   $ git add .github/workflows/release-package.yml .npmrc
   $ git commit -m "Add workflow to pusblish package"
   $ git push

4. Create a release. Click on Releases under Code and click Draft new Release. Create a new tag and enter a title. If you create the release, the workflow will automatically run.

   

5. If the workflow has completed, you can find you package under Code.

   

6. Click on the package to see the details:

   

   Note:
   If you want to create new releases, you have to update the version in package.json. Otherwise the build will fail.

Automatically setting the NPM version

1. Automatically set package number
   You can automate this step by adding the NPM-Version action and set it to the tag of the release:

   - name: 'Change NPM version'
     uses: reedyuk/[email protected]
     with:
       version: ${{github.event.release.tag_name}}

   Add this step to you yaml before the - run: npm ci step and create a new release. The package version is now set automatically to the tag.

2. Calculate the version with GitVersion If you have a more complex workflow you can use GitVersion to calculate your version number. You have to make your checkout shallow for that to work:

     - uses: actions/checkout@v2
       with: 
         fetch-depth: 0

   Now you can install and execute GitVersion and access the version using $GITVERSION_SEMVER:

     - name: Install GitVersion
       uses: gittools/actions/gitversion/[email protected]
       with:
         versionSpec: '5.x'
         
     - name: Determine Version
       id:   gitversion
       uses: gittools/actions/gitversion/[email protected]
       
     - name: 'Change NPM version'
       uses: reedyuk/[email protected]
       with:
         version: $GITVERSION_SEMVER

   Now you could modify your workflow to also trigger on tags or branches to create your package:

   on:
     push: 
       tags:
         - 'v*'
       branches:
         - 'release/*'

Summary

In this module you have learned how to create NPM packages and deploy them to GitHub Packes with automatic versioning.

🥇 Congratulations! You have finished all the exercises of the GitHub Bootcamp worshop.