Publishing Octo to NPM

Hello! Welcome to another blog post about Octo! In this blog post I am going to discuss what I used to publish Octo, the process of how I did it, how I tested it and how to install Octo for yourself!

Getting Ready for Publishing Octo

To start, I used NPM to release Octo to the public.

{
  "name": "octo-ssg",
  "version": "0.1.0",
  "description": "A tool that allows you to generate static sites based off of text data.",
  "main": "bin/app.js",
  "bin": {
    "octo": "./bin/app.js"
  },
  "scripts": {
    "prepare": "husky install",
    "start": "node ./bin/app.js",
    "build": "npm run prettier && npm run eslint-fix && npm run eslint",
    "test": "jest",
    "coverage": "jest --coverage",
    "eslint": "npx eslint .",
    "eslint-fix": "eslint --fix .",
    "prettier": "prettier --write .",
    "prettier-check": "prettier --check ."
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/LuigiZaccagnini/octo.git"
  },
  "keywords": [
    "ssg",
    "static",
    "site",
    "generator"
  ],
  "author": "Luigi Zaccagnini <contact@luigizaccagnini.com> (https://luigizaccagnini.com/)",
  "license": "GPL-3.0-or-later",
  "bugs": {
    "url": "https://github.com/LuigiZaccagnini/octo/issues"
  },
  "homepage": "https://github.com/LuigiZaccagnini/octo#readme",
  "dependencies": {
    "boxen": "^4.2.0",
    "chalk": "2.4",
    "enzyme": "^3.9.0",
    "react": "^16.8.6",
    "react-dom": "^16.8.6",
    "react-test-renderer": "^17.0.2",
    "showdown": "^1.9.0",
    "yargs": "^17.2.1"
  },
  "devDependencies": {
    "eslint": "^8.1.0",
    "husky": "^7.0.4",
    "jest": "^27.3.1",
    "prettier": "2.4.1"
  }
}

I had to go over my package.json to make sure that all my information was correct because this in the information that would be going live. So when you decide to go through with publishing your package, you should make sure your package.json is up to date with information. Once my package.json was good, I had to go through my code and test it to make sure I wasn't publishing a broken tool! Since I have already integrated tools into the project this part was easy (Read Using Static Analysis Tooling with Open Source!, Creating Tests for Octo and Octo: Continuous Integration for more information about adding tools to your project)! Most of my project altering was updating documentation to help users install Octo. Finally push an annotated tag for this release. Since this was Octo's first release I used git tag -a v1.0 -m "version 1.0" to set it as version and git push --follow-tags to push the tag to the repository.

Working with NPM

Now that my project was ready, I created an account at NPM and logged into it through terminal using npm login. You need to confirm you email address for the next steps to work or you will get a 403 error. Another problem I ran into was that if your package name already exists on NPM, you need to change it in your package.json or you will get a 403 Error. This error took me awhile to learn about because the error just stated that I didn't have permission to upload my package. Now that I was logged in and everything is setup correctly, I ran npm publish and Octo was published!

User Testing

For the best user testing I got my sister who is learning web development to try installing my project. I thought this would be perfect because she is using another operating system and I can get a fresh opinion. The main problem I had with the testing was documentation to guide the user to install Octo. When my sister tried to install it on her PC, it wouldn't work because it was not globally installed. So I just fixed the documentation to globally install the project.

How to Install Octo on Your Computer

To install Octo is pretty easy:

Make sure you have Node LTS downloaded and setup on your computer.
Open your terminal/cmd and enter npm i octo-ssg -g
Once installed convert a markdown file to html using octo -i markdownFile.md

Adding CI with NPM Releases

Creating a CI for each release was simple using Github actions. They provided me a template for NPM releases and that was 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: 14
      - run: npm ci
      - run: npm test

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
          registry-url: https://npm.pkg.github.com/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

As you can see above, whenever I push a tag to releases this code will publish Octo to NPM.

Conclusion

I thought this lab would be very difficult because of the daunting idea of having my package on NPM seemed so crazy. The tool I always use for my projects is hosting one of mine, like wow. I am very proud of this achievement and I am very excited with what I can now do with this knowledge. If you have ever published a NPM package comment about what package it is! Thanks for reading, until next time!

Blog