From 87fcc34f9f6e2b4e817a52465248538876ba87ad Mon Sep 17 00:00:00 2001 From: Evan Wallace Date: Sat, 21 Sep 2024 22:08:10 -0400 Subject: [PATCH] update website --- getting-started/index.html | 58 +++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/getting-started/index.html b/getting-started/index.html index 1ac7319..c02ada2 100644 --- a/getting-started/index.html +++ b/getting-started/index.html @@ -140,8 +140,8 @@ os.Exit(1) } } -

If you do this, your dependencies must still be present on the file system at run-time since they are no longer included in the bundle.

Simultaneous platforms

You cannot install esbuild on one OS, copy the node_modules directory to another OS without reinstalling, and then run esbuild on that other OS. This won't work because esbuild is written with native code and needs to install a platform-specific binary executable. Normally this isn't an issue because you typically check your package.json file into version control, not your node_modules directory, and then everyone runs npm install on their local machine after cloning the repository.

However, people sometimes get into this situation by installing esbuild on Windows or macOS and copying their node_modules directory into a Docker image that runs Linux, or by copying their node_modules directory between Windows and WSL environments. The way to get this to work depends on your package manager:

You can also get into this situation on a macOS computer with an ARM processor if you install esbuild using the ARM version of npm but then try to run esbuild with the x86-64 version of node running inside of Rosetta. In that case, an easy fix is to run your code using the ARM version of node instead, which can be downloaded here: https://nodejs.org/en/download/.

Another alternative is to use the esbuild-wasm package instead, which works the same way on all platforms. But it comes with a heavy performance cost and can sometimes be 10x slower than the esbuild package, so you may also not want to do that.

Using Yarn Plug'n'Play

Yarn's Plug'n'Play package installation strategy is supported natively by esbuild. To use it, make sure you are running esbuild such that the current working directory contains Yarn's generated package manifest JavaScript file (either .pnp.cjs or .pnp.js). If a Yarn Plug'n'Play package manifest is detected, esbuild will automatically resolve package imports to paths inside the .zip files in Yarn's package cache, and will automatically extract these files on the fly during bundling.

Because esbuild is written in Go, support for Yarn Plug'n'Play has been completely re-implemented in Go instead of relying on Yarn's JavaScript API. This allows Yarn Plug'n'Play package resolution to integrate well with esbuild's fully parallelized bundling pipeline for maximum speed. Note that Yarn's command-line interface adds a lot of unavoidable performance overhead to every command. For maximum esbuild performance, you may want to consider running esbuild without using Yarn's CLI (i.e. not using yarn esbuild). This can result in esbuild running 10x faster.

Other ways to install

The recommended way to install esbuild is to install the native executable using npm. But you can also install esbuild in these ways:

Download a build

If you have a Unix system, you can use the following command to download the esbuild binary executable for your current platform (it will be downloaded to the current working directory):

curl -fsSL https://esbuild.github.io/dl/v0.23.0 | sh

You can also use latest instead of the version number to download the most recent version of esbuild:

curl -fsSL https://esbuild.github.io/dl/latest | sh

If you don't want to evaluate a shell script from the internet to download esbuild, you can also manually download the package from npm yourself instead (which is all the above shell script is doing). Although the precompiled native executables are hosted using npm, you don't actually need npm installed to download them. The npm package registry is a normal HTTP server and packages are normal gzipped tar files.

Here is an example of downloading a binary executable directly:

curl -O https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.23.0.tgz
-tar xzf ./darwin-x64-0.23.0.tgz
+

If you do this, your dependencies must still be present on the file system at run-time since they are no longer included in the bundle.

Simultaneous platforms

You cannot install esbuild on one OS, copy the node_modules directory to another OS without reinstalling, and then run esbuild on that other OS. This won't work because esbuild is written with native code and needs to install a platform-specific binary executable. Normally this isn't an issue because you typically check your package.json file into version control, not your node_modules directory, and then everyone runs npm install on their local machine after cloning the repository.

However, people sometimes get into this situation by installing esbuild on Windows or macOS and copying their node_modules directory into a Docker image that runs Linux, or by copying their node_modules directory between Windows and WSL environments. The way to get this to work depends on your package manager:

You can also get into this situation on a macOS computer with an ARM processor if you install esbuild using the ARM version of npm but then try to run esbuild with the x86-64 version of node running inside of Rosetta. In that case, an easy fix is to run your code using the ARM version of node instead, which can be downloaded here: https://nodejs.org/en/download/.

Another alternative is to use the esbuild-wasm package instead, which works the same way on all platforms. But it comes with a heavy performance cost and can sometimes be 10x slower than the esbuild package, so you may also not want to do that.

Using Yarn Plug'n'Play

Yarn's Plug'n'Play package installation strategy is supported natively by esbuild. To use it, make sure you are running esbuild such that the current working directory contains Yarn's generated package manifest JavaScript file (either .pnp.cjs or .pnp.js). If a Yarn Plug'n'Play package manifest is detected, esbuild will automatically resolve package imports to paths inside the .zip files in Yarn's package cache, and will automatically extract these files on the fly during bundling.

Because esbuild is written in Go, support for Yarn Plug'n'Play has been completely re-implemented in Go instead of relying on Yarn's JavaScript API. This allows Yarn Plug'n'Play package resolution to integrate well with esbuild's fully parallelized bundling pipeline for maximum speed. Note that Yarn's command-line interface adds a lot of unavoidable performance overhead to every command. For maximum esbuild performance, you may want to consider running esbuild without using Yarn's CLI (i.e. not using yarn esbuild). This can result in esbuild running 10x faster.

Other ways to install

The recommended way to install esbuild is to install the native executable using npm. But you can also install esbuild in these ways:

Download a build

If you have a Unix system, you can use the following command to download the esbuild binary executable for your current platform (it will be downloaded to the current working directory):

curl -fsSL https://esbuild.github.io/dl/v0.24.0 | sh

You can also use latest instead of the version number to download the most recent version of esbuild:

curl -fsSL https://esbuild.github.io/dl/latest | sh

If you don't want to evaluate a shell script from the internet to download esbuild, you can also manually download the package from npm yourself instead (which is all the above shell script is doing). Although the precompiled native executables are hosted using npm, you don't actually need npm installed to download them. The npm package registry is a normal HTTP server and packages are normal gzipped tar files.

Here is an example of downloading a binary executable directly:

curl -O https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.24.0.tgz
+tar xzf ./darwin-x64-0.24.0.tgz
 ./package/bin/esbuild
 Usage:
   esbuild [options] [entry points]
@@ -161,159 +161,159 @@
       @esbuild/aix-ppc64
       aix
       ppc64
-      
+      
       
       
       @esbuild/android-arm
       android
       arm
-      
+      
       
       
       @esbuild/android-arm64
       android
       arm64
-      
+      
       
       
       @esbuild/android-x64
       android
       x64
-      
+      
       
       
       @esbuild/darwin-arm64
       darwin
       arm64
-      
+      
       
       
       @esbuild/darwin-x64
       darwin
       x64
-      
+      
       
       
       @esbuild/freebsd-arm64
       freebsd
       arm64
-      
+      
       
       
       @esbuild/freebsd-x64
       freebsd
       x64
-      
+      
       
       
       @esbuild/linux-arm
       linux
       arm
-      
+      
       
       
       @esbuild/linux-arm64
       linux
       arm64
-      
+      
       
       
       @esbuild/linux-ia32
       linux
       ia32
-      
+      
       
       
       @esbuild/linux-loong64
       linux
       loong642
-      
+      
       
       
       @esbuild/linux-mips64el
       linux
       mips64el2
-      
+      
       
       
       @esbuild/linux-ppc64
       linux
       ppc64
-      
+      
       
       
       @esbuild/linux-riscv64
       linux
       riscv642
-      
+      
       
       
       @esbuild/linux-s390x
       linux
       s390x
-      
+      
       
       
       @esbuild/linux-x64
       linux
       x64
-      
+      
       
       
       @esbuild/netbsd-x64
       netbsd1
       x64
-      
+      
       
       
       @esbuild/openbsd-arm64
       openbsd
       arm64
-      
+      
       
       
       @esbuild/openbsd-x64
       openbsd
       x64
-      
+      
       
       
       @esbuild/sunos-x64
       sunos
       x64
-      
+      
       
       
       @esbuild/win32-arm64
       win32
       arm64
-      
+      
       
       
       @esbuild/win32-ia32
       win32
       ia32
-      
+      
       
       
       @esbuild/win32-x64
       win32
       x64
-      
+      
       
       
-      
Why this is not recommended: This approach only works on Unix systems that can run shell scripts, so it will require WSL on Windows. An additional drawback is that you cannot use plugins with the native version of esbuild.
If you choose to write your own code to download esbuild directly from npm, then you are relying on internal implementation details of esbuild's native executable installer. These details may change at some point, in which case this approach will no longer work for new esbuild versions. This is only a minor drawback though since the approach should still work forever for existing esbuild versions (packages published to npm are immutable).
Install the WASM version
In addition to the esbuild npm package, there is also an esbuild-wasm package that functions similarly but that uses WebAssembly instead of native code. Installing it will also install an executable called esbuild:
npm install --save-exact esbuild-wasm
Why this is not recommended: The WebAssembly version is much, much slower than the native version. In many cases it is an order of magnitude (i.e. 10x) slower. This is for various reasons including a) node re-compiles the WebAssembly code from scratch on every run, b) Go's WebAssembly compilation approach is single-threaded, and c) node has WebAssembly bugs that can delay the exiting of the process by many seconds. The WebAssembly version also excludes some features such as the local file server. You should only use the WebAssembly package like this if there is no other option, such as when you want to use esbuild on an unsupported platform. The WebAssembly package is primarily intended to only be used in the browser.
Deno instead of node
There is also basic support for the Deno JavaScript environment if you'd like to use esbuild with that instead. The package is hosted at https://deno.land/x/esbuild and uses the native esbuild executable. The executable will be downloaded and cached from npm at run-time so your computer will need network access to registry.npmjs.org to make use of this package. Using the package looks like this:
import * as esbuild from 'https://deno.land/x/esbuild@v0.23.0/mod.js'
+      
Why this is not recommended: This approach only works on Unix systems that can run shell scripts, so it will require WSL on Windows. An additional drawback is that you cannot use plugins with the native version of esbuild.
If you choose to write your own code to download esbuild directly from npm, then you are relying on internal implementation details of esbuild's native executable installer. These details may change at some point, in which case this approach will no longer work for new esbuild versions. This is only a minor drawback though since the approach should still work forever for existing esbuild versions (packages published to npm are immutable).
Install the WASM version
In addition to the esbuild npm package, there is also an esbuild-wasm package that functions similarly but that uses WebAssembly instead of native code. Installing it will also install an executable called esbuild:
npm install --save-exact esbuild-wasm
Why this is not recommended: The WebAssembly version is much, much slower than the native version. In many cases it is an order of magnitude (i.e. 10x) slower. This is for various reasons including a) node re-compiles the WebAssembly code from scratch on every run, b) Go's WebAssembly compilation approach is single-threaded, and c) node has WebAssembly bugs that can delay the exiting of the process by many seconds. The WebAssembly version also excludes some features such as the local file server. You should only use the WebAssembly package like this if there is no other option, such as when you want to use esbuild on an unsupported platform. The WebAssembly package is primarily intended to only be used in the browser.
Deno instead of node
There is also basic support for the Deno JavaScript environment if you'd like to use esbuild with that instead. The package is hosted at https://deno.land/x/esbuild and uses the native esbuild executable. The executable will be downloaded and cached from npm at run-time so your computer will need network access to registry.npmjs.org to make use of this package. Using the package looks like this:
import * as esbuild from 'https://deno.land/x/esbuild@v0.24.0/mod.js'
 let ts = 'let test: boolean = true'
 let result = await esbuild.transform(ts, { loader: 'ts' })
 console.log('result:', result)
-await esbuild.stop()
It has basically the same API as esbuild's npm package with one addition: you need to call stop() when you're done because unlike node, Deno doesn't provide the necessary APIs to allow Deno to exit while esbuild's internal child process is still running.
If you would like to use esbuild's WebAssembly implementation instead of esbuild's native implementation with Deno, you can do that by importing wasm.js instead of mod.js like this:
import * as esbuild from 'https://deno.land/x/esbuild@v0.23.0/wasm.js'
+await esbuild.stop()
It has basically the same API as esbuild's npm package with one addition: you need to call stop() when you're done because unlike node, Deno doesn't provide the necessary APIs to allow Deno to exit while esbuild's internal child process is still running.
If you would like to use esbuild's WebAssembly implementation instead of esbuild's native implementation with Deno, you can do that by importing wasm.js instead of mod.js like this:
import * as esbuild from 'https://deno.land/x/esbuild@v0.24.0/wasm.js'
 let ts = 'let test: boolean = true'
 let result = await esbuild.transform(ts, { loader: 'ts' })
 console.log('result:', result)
 await esbuild.stop()
Using WebAssembly instead of native means you do not need to specify Deno's --allow-run permission, and WebAssembly the only option in situations where the file system is unavailable such as with Deno Deploy. However, keep in mind that the WebAssembly version of esbuild is a lot slower than the native version. Another thing to know about WebAssembly is that Deno currently has a bug where process termination is unnecessarily delayed until all loaded WebAssembly modules are fully optimized, which can take many seconds. You may want to manually call Deno.exit(0) after your code is done if you are writing a short-lived script that uses esbuild's WebAssembly implementation so that your code exits in a reasonable timeframe.
Why this is not recommended: Deno is newer than node, less widely used, and supports fewer platforms than node, so node is recommended as the primary way to run esbuild. Deno also uses the internet as a package system instead of existing JavaScript package ecosystems, and esbuild is designed around and optimized for npm-style package management. You should still be able to use esbuild with Deno, but you will need a plugin if you would like to be able to bundle HTTP URLs.
Build from source
To build esbuild from source:
  1. Install the Go compiler:
 
    https://go.dev/dl/
  2. Download the source code for esbuild:
 
    -git clone --depth 1 --branch v0.23.0 https://github.com/evanw/esbuild.git
+git clone --depth 1 --branch v0.24.0 https://github.com/evanw/esbuild.git
 cd esbuild
 
  3. Build the esbuild executable (it will be esbuild.exe on Windows):
 
    go build ./cmd/esbuild
If you want to build for other platforms, you can just prefix the build command with the platform information. For example, you can build the 32-bit Linux version using this command:
GOOS=linux GOARCH=386 go build ./cmd/esbuild
Why this is not recommended: The native version can only be used via the command-line interface, which can be unergonomic for complex use cases and which does not support plugins. You will need to write JavaScript or Go code and use esbuild's API to use plugins.