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

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.

In this tutorial, you will learn 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 a new SDK version:
   • Create an npm account
   • Store an npm API token securely in GitHub
   • Set up a GitHub Action to auto-publish new SDK versions

Prerequisites

This tutorial assumes that you have already developed a functional SDK and pushed it 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 make sure that the option "Allow GitHub Actions to create and approve pull requests" is checked.

Developer:

1. In the root folder of your project, create a directory .github/workflows/. This is where GitHub Action configuration files should always be stored.
2. In this directory, create a new configuration YAML file. Name it release-please.yml.
3. 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.

# 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"

Note that if the main branch of your project has a different name than master (for example main), you need to change this on Line 13.

1. 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.

2. Commit all these changes and push them into the GitHub repository. Now the workflow is set up. The next time someone adds something releasable with a conventional commit message (i.e. with a prefix fix: or feat:), release-please will open a pull request. As you add new 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: Create an npm account, get an API token and store it in GitHub securely

1. Before publishing your SDK for the first time, you need to create an npm account at npmjs.com.
2. Go to your Account > Access Tokens and generate a new Classic Token with type Automation. You can find more info about npm tokens here.
3. Copy the token.
4. Go to the GitHub page of your project. Go to Settings > Security > Secrets and Variables > Actions and click on the "New repository secret" button.
5. Enter NPM_TOKEN in the Name field.
6. Enter the token you copied in Step 3 in the Secret field. Click on the "Add secret" button to confirm.

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 push a release commit into the GitHub origin repository:

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

# https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages

name: Node.js Package

on:
  push:
    branches:
      - master

jobs:
  publish-npm:
    if: contains(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 }}

Note that if the main branch of your project has a different name than master (for example main), you need to change the name on Line 10.

1. Commit this new file to your project 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 containing 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 get in touch with 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?
• Why your product needs an SDK