First NPM package created: GatsbyJS iCalendar Plugin

Today I published my first package at the NPM registry. It is a plugin for the GatbyJS Framework. Gatsby is "a free and open source framework based on React that helps developers build blazing fast websites and apps".

The plugin I created is called gatsby-plugin-ical. With this plugin it's possible to create an iCal feed for events published on the website. I needed this for the haagsemakers.nl website, to create the community events-feed. By adding the published .ics file to your calendar, you have all events in you calendar.

If you want, you can try out the result by adding https://haagsemakers.nl/community-calendar.ics to your calendar.

Publishing a package is a lot easier than I expected. This article describes how I published the package in the npm registry using gitlab, and making sure the gatsby system picks up the package.

Preparations

Publishing a package on the NPM package repository is a lot easier than I expected. It takes some preparations, but overall, it took me about an hour to publish my first package.

Preparing NPM

To be able to publish a package to NPM, you need to create an account. Be sure not to enable 2FA for publishing, because this is not possible with the Continuous Integration setup. Use the command npm login to login on your local computer. After this your API key is visible in the ~/.npmrc file. This key is needed for the Gitlab CI setup in the next step. View this file e.g. by using the command cat ~/npmrc. This will show a line like //registry.npmjs.org/:_authToken=YOUR_API_KEY. The last part is needed for GitLab.

Preparing the repository

I use GitLab for hosting my repositories. You can find the repository here. To make the plugin work for Gatsby, some requirements are needed, especially the keywords section in package.json. These details are listed here)

By adding a postversion script to package.json the publishing process can be further automated:

"scripts": {
  "postversion": "git push --follow-tags"
}

Now, when running npm version 1.0.0 will update the version number in package.json, push the changes to gitlab, and Gitlab CI will publish the package to NPM.

Preparing Gitlab

Gitlab can be setup to publish the package after each build. In my case I chose to publish the repository after each new tagged release. Using the following gitlab-ci.yml publishes the package to npm automatically:

image: node:current
before_script:
  - npm install
cache:
  paths:
    - node_modules/
publish:
  stage: deploy
  only:
    - tags
    - triggers
  script:
    - npm run build
    - echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}'>.npmrc
    - npm publish

Copy the authorization token from the .npmrc file and add it in GitLab as a secret variable named NPM_TOKEN. Now NPM_TOKEN will be available as an environment variable within the GitLab CI jobs. In my case, selecting the protected option for the variable lead to a build error, so I decided to turn this option off. The masked option is turned on.

Publising

With the above setup, publishing a new version of the package is as easy as issuing the command npm version 1.2.3!

One command to push changes, create a tagged release and publish the package to the npm-registry!