2 posts tagged with "javascript"

I have been writing a coupe of NPM packages recently and publishing those NPM packages was quite manual and repetitive. Including bumping versions, changelog and Github releases, the amount of manual work will cost plenty of time. It could easily take up to 30 minutes to have a nicely published NPM package. I then googled the problem and found sementic-release. The tool is very handy as it provides a bunch of cool features due to its plugins system.

semantic-release supports CI workflow as well as local workflow; however, I only used it with a local workflow.

Installation​

In order to start using semantic-release, you will need to setup both NPM token as well as Github token in environment variables. I store them in one of my dotfiles for convenience. An example of my .localrc:

export GH_TOKEN=someveryrandomgithubtoken
export NPM_TOKEN=anothersuperrandomnpmtoken

If you not sure how to generate those tokens, semantic-release-cli can help to generate them in few minutes and initialize configurations for a project. I used it in my first project to get tokens and to be familiar with the tool. I then no longer use it as it keeps asking passwords and MFA token which is inconvenient:

yarn global add semantic-release-cli
semantic-release-cli setup

semantic-release-cli basically adds semantic-release as a development dependency and a couple of configs to package.json.

If GH_TOKEN and NPM_TOKEN are configured, it might be faster to add semantic-release manually:

npm install --save-dev semantic-release

I updated scripts in package.json for convenience:

{
  "scripts": {
    "release": "semantic-release"
  }
}

So I only need yarn release to access its commands.

Configurations​

I use release.config.js for storing configurations. By default, the configuration should be like this:

module.exports = {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github",
  ],
};

With the default configurations, semantic-release will analyze commits using Angular conventions to generate release notes. It then publishes to NPM repository and publishes a new release in Github. It also update package.json for the new package version but committing it. Therefore, an additional plugin is required in order to push the change to Github.

As I also want to generate CHANGELOG and commit the change to my repository automatically, I added two more plugins:

yarn add -D @semantic-release/changelog @semantic-release/git

and in release.config.js:

module.exports = {
  plugins: [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github",
    "@semantic-release/git",
  ],
};

The two new plugins will generate CHANGELOG.md and push it together with package.json to github. You can read more about them in:

• https://github.com/semantic-release/git
• https://github.com/semantic-release/changelog

Release​

After all of those configurations, Release is super simple. After saving your changes to the repository, you can run:

yarn release -d

to review your release notes. After verifying, you can use the following command to publish:

yarn release --no-ci

Then a new version of your package will be published to NPM and Github.

CI​

I didn't set up a CI as one-command release is more than enough for me. If you want to get of your hands free, you can try with Github Actions via this document. Another cool thing about semantic-release is that it can analyze the commit history to decide to change the version accordingly. Basically, everything can be automated.

I was using Gridsome to write this blog from Markdown contents. However, the transformer-remark plugin which transforms a Markdown content to a HTML content doesn't have the functionality to generate an excerpt automatically from the content itself. It requires the excerpt field to be filled manually in front matter. Plus I wanted it so bad that I couldn't wait for the PR to be merged and published to the npm repository. I then decided to create a patch for it so I can have the feature in my own blog as early as possible.

At first, I was thinking of publishing my own package which is a clone of transformer-remark plus the patch. The document is pretty straightforward and I actually used it. However I soon realized that:

• It requires couple of steps to publish to npm.
• We need to maintain the version of the package for new changes.
• It would spam npm with unnecessary content if I keep doing it for every customization.

Later I found out that npm and yarn support to install a package from a git repository. It is so simple that you only need to:

• Patch the change & push it to your own git repository (I would do the same thing for all of my codes).
• Use the npm or yarn command like below to install it:

yarn add https://github.com/bongnv/transformer-remark
// or
npm install https://github.com/bongnv/transformer-remark

As the repository is a public one, any CI should have no problem to install the package from it. You won't need to register for a npm account nor to maintain a version of your package.

It's cool, right? I also happen to learn that beside git repository we can add from a local directory. We can also use yarn link or npm link to link a local fork of the package for testing purpose.