go-npm

Follow these steps to prepare your Go project for NPM distribution:

1. Publish Binaries: Use a tool like GoReleaser to compile and upload your binaries to a server (e.g., GitHub Releases).
2. Initialize NPM: In your project directory (or a separate Git repo), run npm init to create a package.json.
3. Install go-npm: Add go-npm as a development dependency:

   npm install go-npm --save

4. Cleanup: You can delete the node_modules folder after installation, as it is only needed during the publishing process.
5. Configure: Add the postinstall, preuninstall, and goBinary settings to package.json as described in the configuration guide.
6. Publish: Run the following command to make your app available on NPM:

   npm publish

npm init
npm install go-npm --save
rm -r node_modules
npm publish

To integrate go-npm into your application, you must configure your package.json with specific lifecycle scripts and a goBinary configuration object. This tells NPM to trigger the binary download and installation process automatically.

1. Add Lifecycle Scripts

Add postinstall and preuninstall scripts to your package.json to ensure binaries are downloaded upon installation and cleaned up upon uninstallation:

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

2. Define the goBinary Configuration

The goBinary object specifies how to locate and install your binaries. Add this to your package.json:

"goBinary": {
      "name": "command-name",
      "path": "./bin",
      "url": "https://github.com/user/my-go-package/releases/download/v{{version}}/myGoPackage_{{version}}_{{platform}}_{{arch}}.tar.gz"
}

Configuration Keys

• name: The command name users will type in their terminal to run your binary.
• path: The temporary local directory where binaries are downloaded before being moved to NPM's bin directory.
• url: The template URL for your hosted binaries. Use the following placeholders:
  • {{version}}: The version number from your package.json.
  • {{platform}}: The target OS (e.g., windows, darwin, linux).
  • {{arch}}: The target architecture (e.g., amd64, arm64).

{
    "postinstall": "go-npm install",
    "preuninstall": "go-npm uninstall",
    "goBinary": {
      "name": "command-name",
      "path": "./bin",
      "url": "https://github.com/user/my-go-package/releases/download/v{{version}}/myGoPackage_{{version}}_{{platform}}_{{arch}}.tar.gz"
    }
}

To use go-npm to distribute your Go binaries via NPM, you must add a goBinary object to your package.json. The script uses these values to construct the download URL and identify the binary.

Required fields in goBinary:

• name: The name of the binary file (the script automatically appends .exe on Windows).
• path: The local directory where the binary should be temporarily extracted (e.g., ./bin).
• url: The download URL template. You must use placeholders to support different architectures and platforms.

Required top-level field:

• version: The version of your package (the script strips a leading 'v' if present).

Supported URL placeholders:

• {{arch}}: Maps Node's process.arch to Go's $GOARCH (e.g., amd64, arm, 386).
• {{platform}}: Maps Node's process.platform to Go's platform names (e.g., darwin, linux, windows, freebsd).
• {{version}}: The version string from package.json (without a leading 'v').
• {{bin_name}}: The value of goBinary.name (with .exe appended on Windows).

{
  "version": "1.0.0",
  "goBinary": {
    "name": "my-tool",
    "path": "./bin",
    "url": "https://example.com/downloads/my-tool-{{version}}-{{platform}}-{{arch}}.tar.gz"
  }
}