How to publish your NodeJS application on Homebrew
Tags: github, homebrew, cli, node
Published: 2021-04-25 15:09:14

---
title: How to publish your NodeJS application on Homebrew
published: true
date: 2021-04-25 10:50:08 UTC
tags: GitHub,Homebrew,cli,NodeJS
canonical_url: https://bharathvaj.me/blog/how-to-publish-your-nodejs-project-on-homebrew
---

[Homebrew](https://brew.sh) is the de-facto package manager when it comes to **macOS**. It is quite easy to publish your projects on Homebrew without any ruby knowledge.

A couple of years ago, I developed a small CLI utility called [getfilesize-cli](https://github.com/bharathvaj-ganesan/getfilesize-cli). It displays the file size in a human-friendly way. This package is published under [npm](https://www.npmjs.com/) registry but to use this tool the user has to have [NodeJS](https://nodejs.org/en/) runtime installed in the system. As an author, I should make the application easier to install and consume by the users. Therefore, I consider to publish it apart from npm registry.

In this article, I will be showcasing the publishing process used for my tool, `getfilesize-cli`.

## Preparing the binaries

The first step is to create a standalone executable binary where the NodeJS runtime will be baked inside the binary file. For this, I made use of an awesome tool [pkg](https://www.npmjs.com/package/pkg) by [Vercel](https://vercel.com/).

```
npm install pkg -g
pkg package.json
```

This will take package.json as input and bundles all the dependencies along with the NodeJS Alpine runtime.

You can also configure the packaging behavior by adding the following in the `package.json` file.

```
  "pkg": {
    "targets": [
      "node14-linux-x64",
      "node14-macos-x64",
      "node14-win-x64"
    ],
    "outputPath": "release"
  }
```

You will now have a binary executable in the `release/` directory, in my case:

```
<root>/release
```

## Creating Tar File

Homebrew expects a [TAR](https://en.wikipedia.org/wiki/Tar_(computing)) archive, and it’s easy to create one using the commands: _In my case_

```
cd release
mv getfilesize-cli-macos getfilesize
tar -czf getfilesize.tar.gz getfilesize
```

At this point, you should have the `getfilesize.tar.gz` file in your `release` directory.

We also need to get the hash of this tar file while we create [Homebrew formula](https://formulae.brew.sh/).

We can calculate easily that using

```
shasum -a 256 getfilesize.tar.gz
```

## Creating GitHub Releases

Homebrew requires a URL to download your binary. There are plenty of ways to host your executable, but for my project, I used [GitHub Releases](https://help.github.com/en/articles/creating-releases), mainly because it’s free, easy to use, and my project is hosted on it.

Open your project’s GitHub page, navigate to the **Releases section** and then click on **Create a new release**.

Insert a tag version, such as 0.0.1, a title, and then drag the previously created archive ( in my case getfilesize.tar.gz ) into the upload section. You should have something like this:

 ![](https://i.imgur.com/VeZ4sjl.png)

Now click **Publish release** to publish the release.

On the Release page, you’ll need to grab the archive URL. Expand the Assets section and copy the URL of the `getfilesize.tar.gz` archive you’ve just uploaded. In my case:

```
https://github.com/bharathvaj-ganesan/getfilesize-cli/releases/download/v1.0.1/getfilesize.tar.gz
```

 ![](https://i.imgur.com/HMvAvNX.png)

Save it somewhere, we will need it later.

## Preparing the GitHub Repository

Homebrew offers a way to create third-party repositories via [Taps](https://docs.brew.sh/Taps). In a nutshell, Taps are just GitHub repositories with specific names and a few configuration files.

We will need to create one to host our project as follows,

```
homebrew-<projectname>
```

Where _projectname_ is the name of your project. In my case it is `homebrew-getfilesize`

## Creating the Formulae

Please clone the [homebrew-getfilesize](https://github.com/bharathvaj-ganesan/homebrew-getfilesize) repository created in the previous step in your local machine. Now you will need to create a Homebrew Formula for your project, a very simple Ruby file containing the instructions to install your binary on the user computers.

Please note that [Ruby](https://www.ruby-lang.org/en/) knowledge is not required here. (_I don’t know ruby, psst… don’t say to anyone_)

We will need to create the following folder structure,

```
 Formula/
    - getfilesize.rb
 - README.md
```

In the `getfilesize.rb` file, paste the following content:

```
class Getfilesize < Formula
  desc "Get Human Readable file size information. - CLI"
  homepage "https://github.com/bharathvaj-ganesan/getfilesize-cli"
  url "https://github.com/bharathvaj-ganesan/getfilesize-cli/releases/download/v1.0.1/getfilesize.tar.gz"
  sha256 "6c03100f5b1f8e61f5d49efab759a2efcdbcc4ac2677fcf98e7317ec660e6994"
  license "MIT"
  version "1.0.1"

  def install
    bin.install "getfilesize"
  end
end
```

Here,

**desc** - A short description of the package. You can reuse the same from _package.json_

**homepage** - The URL of the repository.

**url** - The path where the TAR file is hosted. The one we got from the release page.

**version** - Your package version. _The one you entered while creating GitHub release_

**license** - License of the package

And finally, change `getfilesize` with your binary executable filename, obtained from the first section:

```
def install
    bin.install "getfilesize"
end
```

Now commit and push your changes to GitHub remote.

## Installing the Package

All right, if you are with me till here, your users are ready to install the package using Homebrew:

```
brew tap bharathvaj-ganesan/getfilesize
brew install getfilesize
```

Where `<user-name>/<repository-name>` is your GitHub username combined with the project name. You can ignore the `homebrew-` prefix while installing and tapping the Formula.

## Next Steps

This was a very basic way to publish your package on Homebrew, but things can get much better. In fact, we can automate the packaging process via [Github Actions](https://github.com/features/actions). DM me if you would like to discuss more on the setup.

If you liked the article and want to stay up to date, follow me on Twitter or GitHub.

## Reference

- [Homebrew Docs](https://docs.brew.sh/)