Add documentation and flow for building without NPM

[MichaelCurrin]

I am interested in using this tool as a binary that can be downloaded, without having Node installed.

This may not be useful for that many developers. Since if you are running ESBuild on JS scripts, you are probably running ESBuild already. But... if you are using Deno (https://deno.land) as a replacement for Node, it is nice to use ESBuild as a minifier tool without having to install Node at all.

Also, if Deno does end up adding a built-in minifier, this issue may not matter as much.

Using Node

Some NPM flows:

• Install globally and use on projects.

  $ npm install -g esbuild

• Install esbuild as a dev dependency and run it as part of npm run to bundle and minify scripts.
• Use npx, as suggested on a Deno issue thread.

  $ npx esbuild --minify ...

Maybe it is worth documenting these Node flows above as multiple ways to install and run ESBuild.

Using Go

Here is a solution without Node installed.

$ # Install
$ go get -u github.com/evanw/esbuild/cmd/esbuild

$ # Check and use installed binary.
$ which esbuild
/Users/mcurrin/go/bin/esbuild
$ esbuild -h

Maybe it is worth documenting that somewhere.

However, the Go flow above requires Go to be installed. And requires one to have a Go 1.16 (actually only enforced with Makefile but not enforced if using go get

Without Node or Go

I am thinking about how to get a copy of ESBuild on my machine or on GH Actions CI without Node or Go installed.

The solution I think is to prepare a compiled binary and make it ready for download on GitHub Releases under "Assets", or a "Download" page on the website. This could be generated automatically on master when a Tag/Release is generated.

If you use an Action like Go Releaser, this is even easier. It will even build multiple outputs across macOS, Windows, etc. so someone can download a copy suitable for their OS.

https://michaelcurrin.github.io/code-cookbook/recipes/ci-cd/github-actions/workflows/go/go-releaser.html

Example assets: https://github.com/trashhalo/imgcat/releases/tag/v1.2.0

[MichaelCurrin]

Thanks!

[evanw]

You can download the precompiled binaries from npm without needing npm installed if you'd like. Here is an example of how to do this:

$ curl -O https://registry.npmjs.org/esbuild-darwin-64/-/esbuild-darwin-64-0.8.55.tgz
$ tar xf ./esbuild-darwin-64-0.8.55.tgz
$ ./package/bin/esbuild

Usage:
  esbuild [options] [entry points]

...

You can also get at them through any of the various npm CDNs if you prefer to not call tar to unzip the archive. I can't personally vouch for their security practices so it'd be up to you how much you trust them vs. npm itself. Here's an example:

$ curl -O https://unpkg.com/[email protected]/bin/esbuild
$ chmod +x esbuild
$ ./esbuild

Usage:
  esbuild [options] [entry points]

...

[MichaelCurrin]

Ok great, thanks.

[MichaelCurrin]

I tried something similar before JSDelivr. Why didn't that work?

https://www.jsdelivr.com/package/npm/esbuild?path=bin

$ curl -O https://cdn.jsdelivr.net/npm/[email protected]/bin/esbuild

That is just a short file that tells you that you don't have the binary installed.

#!/usr/bin/env node
throw new Error(`esbuild: Failed to install correctly

Make sure you don't have "ignore-scripts" set to true. You can check this with...
...
`)

[MichaelCurrin]

Oh I see you specified esbuild-darwin-64 not esbuild.

Found it here as another package https://www.jsdelivr.com/package/npm/esbuild-darwin-64?path=bin

I wasn't aware that binaries are distributed as separated packages on NPM.

[evanw]

The full list of package names for available platform architectures is here:

esbuild/lib/install.ts

Lines 277 to 286 in 15b36c5

	'darwin x64 LE': 'esbuild-darwin-64',
	'darwin arm64 LE': 'esbuild-darwin-arm64',
	'freebsd arm64 LE': 'esbuild-freebsd-arm64',
	'freebsd x64 LE': 'esbuild-freebsd-64',
	'linux arm LE': 'esbuild-linux-arm',
	'linux arm64 LE': 'esbuild-linux-arm64',
	'linux ia32 LE': 'esbuild-linux-32',
	'linux mips64el LE': 'esbuild-linux-mips64le',
	'linux ppc64 LE': 'esbuild-linux-ppc64le',
	'linux x64 LE': 'esbuild-linux-64',

[MichaelCurrin]

Perfect. Then now I have a way do this on Linux and macOS.

A short page in docs would be able to resolve this as an issue. That could cover the curl instructions you gave above. And a link to install.ts file.

[evanw]

Alternative installation methods are now documented here: https://esbuild.github.io/getting-started/#other-ways-to-install. Closing.

[osdevisnot]

👋 @MichaelCurrin, if it makes it any easier for your workflow, you can also install esbuild using go binaries:

curl -sf https://gobinaries.com/evanw/esbuild/cmd/esbuild | sh

I am not sure if @evanw prefers this installation method, but it certainly is much faster than NPM/yarn install.

[evanw]

I am not sure if @evanw prefers this installation method

I will not be personally recommending this installation workflow because I don't know why I should trust gobinaries.com with the security of my computer, and so I shouldn't expect others to either. It's great if it works for you but I don't feel good putting it in esbuild's documentation since it's not an official Go project.

[MichaelCurrin]

Thanks @evanw - the instructions look great.

[MichaelCurrin]

Thanks @osdevisnot - I hadn't heard of that project. Fascinating ideas.

From GitHub https://github.com/tj/gobinaries

Go Binaries is an on-demand binary server, allowing non-Go users to quickly install tools written in Go without installing go itself, and removing the burden of cross-compiling and uploading dozens of binaries for every command-line you write.

But good to hear that point around security from @evanw .