Release and publish a new JavaScript SDK version automatically: a step-by-step guide

Introduction

Maintaining a well-organized changelog, releasing a new version of an SDK, then publishing it into a package repository. All these are tedious, repetitive chores that can be automated to save valuable developer time.

This tutorial will teach you how to set up tools that do just that. You will walk through the following steps:

1. Set up a Github Action to release a new SDK version
2. Publish new SDK versions:
   1. Create an npm account
   2. Store an npm API token securely in GitHub
   3. Set up a GitHub Action to auto-publish new SDK versions

Prerequisities

This tutorial assumes that you have already developed and pushed a functional SDK into a GitHub repository.

Release a new version

Owner + Developer: Set up a Github Action to release new SDK versions

To avoid the tedious task of updating the changelog and releasing new versions manually, we recommend using the Github Action release-please. This Action keeps track of code changes since the last release and maintains a pull request with changelog and version changes based on your commit messages. When the time is right to release a new SDK version, all you need to do is merge the pull request.

Follow these steps to set up the Action:

Owner

1. In your GitHub repository, go to Settings > Actions > General and check the option “Allow GitHub Actions to create and approve pull requests” is checked.

Developer

2. In the root folder of your project, create a directory .github/workflows/. This is where GitHub Action configuration files should always be stored.
3. In this directory, create a new configuration YAML file. Name it release-please.yml.
4. Copy the following code into your configuration file:  

# This workflow opens and updates a pull request with a new package version
# based on code changes.
# The pull request updates the version in package.json, updates the changelog
# and creates release tags.
# For more information, see https://github.com/marketplace/actions/release-please-action

on:
 push:
   branches:
     - master

permissions:
 contents: write
 pull-requests: write

name: release-please
jobs:
 release-please:
   runs-on: ubuntu-22.04
   steps:
     - uses: google-github-actions/release-please-action@v3.7.10
       with:
         release-type: node
         package-name: release-please-action
         pull-request-title-pattern: "chore(release): ${version}"
         pull-request-header: ":robot: Merge this PR to release a new version"       

5. If your SDK has been released before, make sure that the commit with the latest release has a version tag attached to it (in the format “v2.1.1”) and that this tag has been pushed to GitHub. The release-please tool determines the next version number based on this tag. Unless such a tag exists, release-please will suggest “v1.0.0” as the next version number.
6. Commit all these changes and push this commit into the GitHub repository. The next time you commit a new bug fix (“fix: …”) or a feature (“feat: …”), release-please will open a new pull request. As you add more code, the pull request will be updated automatically. When you are eventually ready to roll out a new version of your SDK, simply merge this pull request.

Note that release-please follows the Semantic Versioning (SemVer) specification, which means that it will automatically generate version numbers based on the significance of your changes. For example, if you have made breaking changes, it will generate a major version number; if you have added new features, it will generate a minor version number; and if you have fixed bugs, it will generate a patch version number. By following this convention, you can make it easy for your users to understand the impact of each new version of your SDK.

Your commit messages should follow the Conventional Commits format for release-please to be able to determine the significance of your changes and generate the correct version number. This means that you should follow a specific format for your commit messages, such as "feat: add new feature" for a new feature, "fix: resolve bug" for a bug fix, and "chore: update dependencies" for a non-code change. By using this format consistently, you can ensure that release-please generates version numbers and changelogs correctly based on the significance of your changes. You can, however, always update the changelog manually in the open pull request before the release.

Publish the SDK

Owner: Setting up secrets

As the owner of the SDK, you will need to set up secrets in your repository to store your npm token. Here are the steps to set up secrets:

1. Sign up on https://www.npmjs.com/, go to your “Account” > “Access Tokens”, and generate a new Classic Token with type Automation (get more info here).
2. In your repository on GitHub, where you want to set the automation, go to "Settings" > "Secrets and variables" > “Actions” and click on the "New repository secret" button.
3. In the "Name" field, enter NPM_TOKEN.
4. In the "Secret" field, paste the token you just created on npmjs.com.
5. Click on the "Add secret" button to save your npm token as a secret.

Now your npm token is securely stored in your repository and can be accessed by your GitHub Action. When the GitHub Action runs, it will use the token to authenticate with the npm registry and publish your SDK.

Note that you should never share your npm token with anyone and avoid committing it to your codebase. By using secrets, you can ensure that your token is only accessible to authorized users and that it is not exposed in your code.

Developer: Automate SDK publishing using GitHub Actions

You can set up a GitHub Action that will automatically publish your SDK to the npm repository after you release a new version:

1. In your project, go to the folder .github/workflows (or create it if it does not exist yet) and create a new configuration YAML file. Name it, for example, npm-publish.yml.
2. Copy the following code into your configuration file:

# This workflow will publish a package to npmjs.com when a release is created
# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages

name: Node.js Package

on:
 push:
   branches:
     - master
jobs:
 publish-npm:
   if: contain(github.event.head_commit.message, 'chore(release)')
   runs-on: ubuntu-latest
   steps:
     - uses: actions/checkout@v3.5.3
     - uses: actions/setup-node@v3.7.0
       with:
         node-version: 18.16.1
         registry-url: https://registry.npmjs.org/
     - run: npm publish --access public
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

3. Commit this new file to your project's main branch and push these changes into the GitHub origin repository.

Now, the GitHub Action is ready. Note that for the Action to work, you need to add the `NPM_TOKEN` to GitHub secrets first.

The Action is triggered when you push a commit into your main project branch with the commit message starting with the phrase "chore(release)". If you took the steps described in the “Release a new version” section of this manual, the publish Action will be triggered when you merge the pull request opened by the release-please Action.

Conclusion

This guide walked you through the process of setting up automatic tools for releasing a new version of a JavaScript SDK and publishing it into the npm repository. By automating these processes, you save time and resources that you can instead dedicate to developing your code.

If you need help with SDK development or automation setup, our team of experts is ready to assist you. We can help you streamline your SDK development process, optimize your automation setup, and save you time and money in the process.

So why not contact us today and see how we can help you take your SDK development to the next level?

Need an automated release for another technology?

• Automated release for Ruby
• Automated release for PHP
• Explore our tool that automates all technologies at once

You might also be interested in:
SDK: What is it and how can it help my business? 

Author

Prokop Simek

CEO

With more than 12 years in software engineering, I use my expertise to link business and technology for our clients.