
In the world of [Node.js](https://nodejs.org/), you're gonna be using the [npm cli tool](https://www.npmjs.com/). You're
also going to find lots of blogs telling you how to do things but I constantly find one piece of info lacking and
surprisingly, this is about installing node modules in a project. Well, I guess there are two things that are related
and one sort of makes the other moot.

## Version Pinning

One thing I always try to get people to do is pin versions of their dependencies in `package.json`. What pinning does is
makes anyone installing the dependencies always have the same version. By default, npm adds the `~` prefix to the
versions so if you were to `npm i @mitchellsimoens/versionator` it will use `^1.0.5` as the version. This means, if
1.0.6 or 1.1.0 is released, someone could have a different version that has been untested and may have features not
present in older versions. This can add confusion but even worse, this can add risk (even for
[attacks](https://eslint.org/blog/2018/07/postmortem-for-malicious-package-publishes)). The `~` prefix is a little better
but the same issues can still occur only it locks down the possibilities to patch versions not minor versions.

So what's the big deal? In today's world, we have to admit we freely install node modules from anyone. This means we
put a lot of faith in people and while I would hope people have great intentions, some don't and even great intentions
aren't perfect. Also, not everyone follows semver strictly so a minor version maybe should have been a major.

You're best to protect yourself as best as you can by pinning versions. I even change the default to always pin via
npm's config:

```sh
npm config set save-exact=true
```

I'll be honest though, this is a bit of a false sense of security as it's not 100% but it's at least some form of
prevention. Someone I work with found this [blog post](https://docs.renovatebot.com/dependency-pinning/) that does a
great job at some pros/cons of version pinning so I definitely think that is worth a read.

## The Right Command

The other thing sort of makes version pinning moot. Say you clone a repo that contains a node project, what do you do
first? I bet you run `npm install` (or `npm i`). You just used the wrong command. Instead, and hopefully everyone checks
in the `package-lock.json` into VCS, you should get into the habit of using `npm ci`. What this command does is installs
what is in `package-lock.json`. If you used `npm install`, npm will go and try to find the latest version of your
dependencies (and their dependencies) that match the version and version prefixes come into play then. Npm will then
update the `package-lock.json` with these updated versions and you just introduced risk.

In fact, I ran a quick poll of some colleagues and 10 out of 11 (the poll got pushed way off screen with all the
replies) used `npm install` and some didn't even know about `npm ci`. The one person is someone I work with a lot so
wasn't a surprise there. This is also why I will still pin versions to get at least some sort of protection from those
not using `npm ci` when they should.

If you are adding a dependency, then use `npm install` since that will just add the dependency(ies) and not upgrade all
existing dependencies. If you are wanting to install all dependencies then use `npm ci` and protect yourself.


NPM Install


I've seen a few blogs about publishing a node module to the [NPM] repository and
[GitHub Package Registry (GPR)][gpr]. Some I like, some I don't. I thought, what's better than a couple
existing blogs about it? One more. I also have some ideas for the stuff I've done that may be a bit unique to
me but the workflow I have can be easily adjusted to remove parts if that isn't desired.

## The Why

Why publish a node module to NPM and GPR? Being the default, publishing to NPM is still a great idea. However,
lately, I've seen some projects start going with GPR also. Yes, installing a node module that your `.npmrc` is
targeting GPR will still get proxied to NPM, I still feel it could be a good idea to also publish to GitHub. I
also want to have a GitHub release created without just relying on a git tag.

## Splitting the workflow

The workflow I will be talking about has 4 jobs:

- [`build`](#build-job)
- [`release`](#release-job) (requires `build` job)
- [`publish-npm`](#publish-npm-job) (requires `build` job)
- [`publish-gpr`](#publish-gpr-job) (requires `build` job)

The last three rely on the `build` job but allow those three to run in parallel. Let's look more at each
individually but at the end I'll still show the entire `.github/workflows/publish.yml` file.

### `build`<a name="build-job"></a>

```yml
build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v1
    - uses: actions/setup-node@v1
      with:
        node-version: 14
    - run: npm ci
    - run: npm run lint
    - run: npm test
    - run: npm run build
    - name: Zip lib & node_modules
      run: zip -9qry "build.zip" "./" -i "node_modules/*" -i "lib/*"
    - name: Upload build.zip
      uses: actions/upload-artifact@v2
      with:
        name: build.zip
        path: build.zip
```

I personally use [TypeScript] a lot so I need do need to build it. I also like to run a quick lint check and
run tests as this is the last opportunity to stop a release.I also zip up the build artifacts (`node_modules`
and `lib` in this case) and then upload them so the subsequent steps can download it and use it.

One thing not to overlook is when installing I use `npm ci` instead of `npm i` so that I only install what is
in the lock file and nothing possibly new. I see people using `npm i` far too many times even during
development. Updating dependencies should be a planned thing and not happen just whenever anyone feels like it.

If you don't use TypeScript or anything else that would require a build, you can simply remove that step and
the `lib` dir from the zipping but I still would zip and upload the `node_modules` dir. This would then look
like this:

```yml
build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v1
    - uses: actions/setup-node@v1
      with:
        node-version: 14
    - run: npm ci
    - run: npm run lint
    - run: npm test
    - name: Zip lib & node_modules
      run: zip -9qry "build.zip" "./" -i "node_modules/*"
    - name: Upload build.zip
      uses: actions/upload-artifact@v2
      with:
        name: build.zip
        path: build.zip
```

The same would be true if you didn't have or didn't want to run the lint check or tests.

### `release`<a name="release-job"></a>

```yml
release:
  needs: build
  name: Create GitHub Release
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@master
    - name: Download build.zip
      uses: actions/download-artifact@v2
      with:
        name: build.zip
    - name: Create Release
      id: create_release
      uses: actions/create-release@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        tag_name: ${{ github.ref }}
        release_name: Release ${{ github.ref }}
        body: Stuff happened
    - name: Upload Release Asset
      uses: actions/upload-release-asset@v1
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        upload_url: ${{ steps.create_release.outputs.upload_url }}
        asset_path: ./build.zip
        asset_name: build.zip
        asset_content_type: application/zip
```

This is where things start happening. Creating GitHub releases is a great thing as it allows you to hold build
artifacts and have some body describing things in that release. There are many ways to build the body of the
release so I left it simple in this workflow as I've had to do many different things. Notice here, we download
the zipped build artifact but we don't unzip it. We upload that zip to the release after it has been created.
The reason for this is when the `create_release` step executes, it actually hits GitHubs create release API
which then uses the source for that tag. This is important as it does not create a release from what is
currently on disk so if you did this after a build (or unzipped the build artifact), that wouldn't show up
in the GitHub release.

I think it's important to upload the build artifact to the GitHub release so you have that zip bound to that
release which does include the `node_modules` dir. This is important because many people have dependencies in
their `package.json` with a prefix meaning the versions of the dependencies are not locked. When not locked,
you can never count on installing that exact version without some work. So upload the build artifact and you
are good to go without any work.

If you don't know, when you see `${{ secrets.GITHUB_TOKEN }}` that does not mean you need to go into the repo
settings and add a secret. That is a special secret that is generated for you when it's used. Also, the
`actions/create-release` action specially handles the `${{ github.ref }}` to strip away the `refs/tags/` part
to just have the actual tag name. So the `${{ github.ref }}` would really look like `refs/tags/v1.0.0` but
it removes it and so you'd just have `v1.0.0`.

### `publish-npm`<a name="publish-npm-job"></a>

```yml
publish-npm:
  needs: build
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v1
    - uses: actions/setup-node@v1
      with:
        node-version: 14
        registry-url: https://registry.npmjs.org/
    - name: Download build.zip
      uses: actions/download-artifact@v2
      with:
        name: build.zip
    - name: Unzip build.zip
      run: unzip -q build.zip
    - run: npm publish --access public
      env:
        NODE_AUTH_TOKEN: ${{secrets.PUBLISH_NPM_TOKEN}}
```

Publishing to NPM step is pretty simple. We setup node setting the registry url to NPM, then download the
build artifact from the [`build`](#build-job) step, unzip it so that the `lib` directory is present and then
run `npm publish`. This step does require you to create a token over on [NPM] and add it as a secret to your
repo settings.

### `publish-gpr`<a name="publish-gpr-job"></a>

```yml
publish-gpr:
  needs: build
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v1
    - uses: actions/setup-node@v1
      with:
        node-version: 14
        registry-url: https://npm.pkg.github.com/
        scope: '@mitchellsimoens'
    - name: Download build.zip
      uses: actions/download-artifact@v2
      with:
        name: build.zip
    - name: Unzip build.zip
      run: unzip -q build.zip
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{secrets.PUBLISH_GITHUB_TOKEN}}
```

The publish to GPR is very similar to the [`publish-npm`](#publish-npm-job) but there are a few differences.
First, when we setup node we give it a different registry-url but we also need to specify the scope. All this
is is the username or organization name the repo is under. So for me, if I have the repo
https://github.com/mitchellsimoens/foo then `@mitchellsimoens` is the scope. The next difference is of course
we need a [GitHub token](https://github.com/settings/tokens) which needs the `write:packages` scope (this will
also automatically check all the `repo.*` and `read:packages` scopes). A keen eye also would notice that the
`npm publish` here doesn't have the `--access public` because with GPR the access is determined by the scopes
on the user token being used.

## The whole workflow

The whole workflow is mostly all of the above concatenated but it also includes what triggers the workflow. I
have mine trigger when a tag with the `v` prefix is pushed. This means, I run `npm version patch` (or whatever
version) and then push the commit and tag up. I've seen some people push all tags (`git push --tags`) which is
fine but if there are any other tags with `v` prefix in it that have not been pushed you could trigger unwanted
publishes so you may want to push a single tag like `git push origin v1.0.0`. Up to you if you care about that.

Ok, here is the full workflow I normally put as `.github/workflow/publish.yml`:

```yml
name: Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 14
      - run: npm ci
      - run: npm run lint
      - run: npm run build
      - name: Zip lib & node_modules
        run: zip -9qry "build.zip" "./" -i "node_modules/*" -i "lib/*"
      - name: Upload build.zip
        uses: actions/upload-artifact@v2
        with:
          name: build.zip
          path: build.zip

  release:
    needs: build
    name: Create GitHub Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - name: Download build.zip
        uses: actions/download-artifact@v2
        with:
          name: build.zip
      - name: Create Release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
      - name: Upload Release Asset
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./build.zip
          asset_name: build.zip
          asset_content_type: application/zip

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 14
          registry-url: https://registry.npmjs.org/
      - name: Download build.zip
        uses: actions/download-artifact@v2
        with:
          name: build.zip
      - name: Unzip build.zip
        run: unzip -q build.zip
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{secrets.PUBLISH_NPM_TOKEN}}

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 14
          registry-url: https://npm.pkg.github.com/
          scope: '@mitchellsimoens'
      - name: Download build.zip
        uses: actions/download-artifact@v2
        with:
          name: build.zip
      - name: Unzip build.zip
        run: unzip -q build.zip
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.PUBLISH_GITHUB_TOKEN}}
```

[gpr]: https://github.com/features/packages
[npm]: https://www.npmjs.com/
[typescript]: https://www.typescriptlang.org/
