npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@dkhrunov/go-npm

v0.2.5

Published

Distribute and install Go binaries via NPM

Downloads

13

Readme

Go NPM

(@dkhrunov): MODIFICATIONS FROM @go-task/go-npm FORK

  • Added "token" field to "goBinary" in package.json for private git repos. In this field you indicate not the token itself, but an env variable that stores the value of the token.

(@go-task): MODIFICATIONS FROM gzuidhof/go-npm FORK

  • Added {{archive_ext}} to recognize .zip packages on Windows and .tar.gz on macOS and Linux.
  • Fixed error when trying to remove the binary from a previous installation.
  • Add support for local npm prefix (#1).
  • Added support for pnpm (#3).
  • Fixed installation path on Windows (#4, #5).
  • Fixed installation path in newer Node versions (go-task/task#1190, #8).
  • Migrate from unzipper to adm-zip to fix ZIP extraction bugs (#7, #9).

(@gzuidhof): MODIFICATIONS FROM BASE go-npm PACKAGE

  • Support for zip and non-compressed binaries.
  • Added support for arm64 architecture.
  • Fix for use on Windows platform (the binary would get placed in the wrong place for consumers).
  • Shipped as a bundle using esbuild, removing 70 packages of dependencies (including huge things like Babel). Now your users will only have to download one additional package (@gzuidhof/go-npm).

Distribute cross-platform Go binaries via NPM

Applications written in Golang are portable - you can easily cross-compile binaries that work on Windows, Mac, and Linux. But how do you distribute the binaries to customers? When you publish new releases, how do they update the binary?

Use NPM to distribute cross-platform Go binaries

Kidding me! Why NPM?

  • Cross-platform: NPM is the only popular package manager that works cross-platform.
  • Lower barier to entry: Most developers have NPM installed already.
  • Pain free publishing: It just takes one command to publish - npm publish
  • Dead simple install & update story: npm install/update -g your-awesome-app
  • Adds $PATH: NPM will automatically add your binary location to $PATH and generate .cmd file for Windows. Your app just works after installation!

Okay, tell me how?

1. Publish your binaries

Setup your Go application to compile and publish binaries to a file server. This could be Github Releases or Amazon S3 or even Dropbox. All you need is a link.

I like to use GoReleaser to setup by release process. You create a simple YAML configuration file like this and run goreleaser CLI to publish binaries for various platform/architecture combination to Github:

# .goreleaser.yml
# Build customization
builds:
  - binary: drum-roll
    goos:
      - windows
      - darwin
      - linux
    goarch:
      - amd64

go-npm will pull the appropriate binary for the platform & architecture where the package is being installed.

2. Create a package.json file for your NPM app

To publish to NPM, you need to create a package.json file. You give your application a name, link to Readme, Github repository etc, and more importantly add go-npm as a dependency. You can create this file in an empty directory in your project or in a separate Git repository altogether. It is your choice.

Create package.json

$ npm init

Answer the questions to create an initial package.json file

Add go-npm dependency

From the directory containing package.json file, do

$ npm install @dkhrunov/go-npm --save

This will install go-npm under to your package.json file. It will also create a node_modules directory where the go-npm package is downloaded. You don't need this directory since you are only going to publish the module and not consume it yourself. Let's go ahead and delete it.

$ rm -r node_modules

Add postinstall and preuninstall scripts Here is the magic: You ask to run go-npm install after it completes installing your package. This will pull down binaries from Github or Amazon S3 and install in NPM's bin directory. Binaries under bin directory are immediately available for use in your Terminal.

Edit package.json file and add the following:

"scripts": {
    "postinstall": "go-npm install",
    "preuninstall": "go-npm uninstall",
}

go-npm uninstall simply deletes the binary from bin directory before NPM uninstalls your package.

Configure your binary path

You need to tell go-npm where to download the binaries from, and where to install them. Edit package.json file and add the following configuration.

"goBinary": {
      "name": "command-name",
      "path": "./bin",
      "url": "https://github.com/user/my-go-package/releases/download/v{{version}}/myGoPackage_{{version}}_{{platform}}_{{arch}}.tar.gz"
      "token": "GIT_HUB_TOKEN"
  • name: Name of the command users will use to run your binary.
  • path: Temporary path where binaries will be downloaded to
  • url: HTTP Web server where binaries are hosted.

Following variables are available to customize the URL:

  • {{version}}: Version number read from package.json file. When you publish your package to NPM, it will use this version number. Ex: 0.0.1
  • {{platform}}: $GOOS value for the platform
  • {{arch}}: $GOARCH value for the architecture
  • {{win_ext}}: optional .exe extension for windows assets.
  • {{archive_ext}}: outputs .zip on Windows or .tar.gz on macOS and Linux.

If you use goreleaser to publish your modules, it will automatically set the right architecture & platform in your URL.

Publish to NPM

All that's left now is publish to NPM. As I promised before, just one command

$ npm publish

3. Distribute to users

To install:

npm install -g your-app-name

To Update:

npm update -g your-app-name


With ❤️ to the community by Sanath Kumar Ramesh