Getting Started

Install esbuild

First, download and install the esbuild command locally. A prebuilt native executable can be installed using npm:

npm install esbuild

This should have installed esbuild in your local node_modules folder. You can run the esbuild executable to verify that everything is working correctly:

./node_modules/.bin/esbuild --version

.\node_modules\.bin\esbuild --version

The recommended way to install esbuild is to install the native executable using npm. But if you don't want to do that, there are also some other ways to install.

Your first bundle

This is a quick real-world example of what esbuild is capable of and how to use it. First, install the react and react-dom packages:

npm install react react-dom

Then create a file called app.jsx containing the following code:

import * as React from 'react'
import * as Server from 'react-dom/server'

let Greet = () => <h1>Hello, world!</h1>
console.log(Server.renderToString(<Greet />))

Finally, tell esbuild to bundle the file:

./node_modules/.bin/esbuild app.jsx --bundle --outfile=out.js

.\node_modules\.bin\esbuild app.jsx --bundle --outfile=out.js

This should have created a file called out.js containing your code and the React library bundled together. The code is completely self-contained and no longer depends on your node_modules directory. If you run the code using node out.js, you should see something like this:

<h1 data-reactroot="">Hello, world!</h1>

Notice that esbuild also converted JSX syntax to JavaScript without any configuration other than the .jsx extension. While esbuild can be configured, it attempts to have reasonable defaults so that many common situations work automatically. If you would like to use JSX syntax in .js files instead, you can tell esbuild to allow this using the --loader:.js=jsx flag. You can read more about the available configuration options in the API documentation.

Build scripts

Your build command is something you will be running repeatedly, so you will want to automate it. A natural way of doing this is to add a build script to your package.json file like this:

{
  "scripts": {
    "build": "esbuild app.jsx --bundle --outfile=out.js"
  }
}

Notice that this uses the esbuild command directly without a relative path. This works because everything in the scripts section is run with the esbuild command already in the path (as long as you have installed the package).

The build script can be invoked like this:

npm run build

However, using the command-line interface can become unwieldy if you need to pass many options to esbuild. For more sophisticated uses you will likely want to write a build script in JavaScript using esbuild's JavaScript API. That might look something like this:

require('esbuild').build({
  entryPoints: ['app.jsx'],
  bundle: true,
  outfile: 'out.js',
}).catch(() => process.exit(1))

The build function runs the esbuild executable in a child process and returns a promise that resolves when the build is complete. The code above doesn't print out the captured exception because any error messages in the exception will also be printed to the console by default (although you can change the log level to turn that off if you'd like).

Although there is also a buildSync API that is not asynchronous, the asynchronous API is better for build scripts because plugins only work with the asynchronous API. You can read more about the configuration options for the build API in the API documentation.

Bundling for the browser

The bundler outputs code for the browser by default, so no additional configuration is necessary to get started. For development builds you probably want to enable source maps with --sourcemap, and for production builds you probably want to enable minification with --minify. You probably also want to configure the target environment for the browsers you support. All of that might looks something like this:

esbuild app.jsx --bundle --minify --sourcemap --target=chrome58,firefox57,safari11,edge16

require('esbuild').buildSync({
  entryPoints: ['app.jsx'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
  outfile: 'out.js',
})

package main

import "github.com/evanw/esbuild/pkg/api"
import "os"

func main() {
  result := api.Build(api.BuildOptions{
    EntryPoints:       []string{"app.jsx"},
    Bundle:            true,
    MinifyWhitespace:  true,
    MinifyIdentifiers: true,
    MinifySyntax:      true,
    Engines: []api.Engine{
      {api.EngineChrome, "58"},
      {api.EngineFirefox, "57"},
      {api.EngineSafari, "11"},
      {api.EngineEdge, "16"},
    },
    Write: true,
  })

  if len(result.Errors) > 0 {
    os.Exit(1)
  }
}

Sometimes a package you want to use may import another package that is only available on node, such as the built-in path package. When that happens you can substitute the package for a browser-friendly alternative by using the browser field in your package.json file like this:

{
  "browser": {
    "path": "path-browserify"
  }
}

Some npm packages you want to use may not be designed to be run in the browser. Sometimes you can use esbuild's configuration options to work around certain issues and successfully bundle the package anyway. Undefined globals can be replaced with either the define feature in simple cases or the inject feature in more complex cases.

Bundling for node

Even though a bundler is not necessary when using node, sometimes it can still be beneficial to process your code with esbuild before running it in node. Bundling can automatically strip TypeScript types, convert ECMAScript module syntax to CommonJS, and transform newer JavaScript syntax into older syntax for a specific version of node. And it may be beneficial to bundle your package before publishing it so that it's a smaller download and so it spends less time reading from the file system when being loaded.

If you are bundling code that will be run in node, you should configure the platform setting by passing --platform=node to esbuild. This simultaneously changes a few different settings to node-friendly default values. For example, all packages that are built-in to node such as fs are automatically marked as external so esbuild doesn't try to bundle them. This setting also disables the interpretation of the browser field in package.json.

If your code uses newer JavaScript syntax that doesn't work in your version of node, you will want to configure the target version of node:

esbuild app.js --bundle --platform=node --target=node10.4

require('esbuild').buildSync({
  entryPoints: ['app.js'],
  bundle: true,
  platform: 'node',
  target: ['node10.4'],
  outfile: 'out.js',
})

package main

import "github.com/evanw/esbuild/pkg/api"
import "os"

func main() {
  result := api.Build(api.BuildOptions{
    EntryPoints: []string{"app.js"},
    Bundle:      true,
    Platform:    api.PlatformNode,
    Engines: []api.Engine{
      {api.EngineNode, "10.4"},
    },
    Write: true,
  })

  if len(result.Errors) > 0 {
    os.Exit(1)
  }
}

Sometimes the packages you want to use contain code that can't be bundled for some reason. An example of this is a package with native extensions such as fsevents. Or, you may want to exclude a package from the bundle for other reasons. This can be done by marking the package as external:

esbuild app.jsx --bundle --platform=node --external:fsevents

require('esbuild').buildSync({
  entryPoints: ['app.jsx'],
  bundle: true,
  platform: 'node',
  external: ['fsevents'],
  outfile: 'out.js',
})

package main

import "github.com/evanw/esbuild/pkg/api"
import "os"

func main() {
  result := api.Build(api.BuildOptions{
    EntryPoints: []string{"app.jsx"},
    Bundle:      true,
    Platform:    api.PlatformNode,
    External:    []string{"fsevents"},
    Write:       true,
  })

  if len(result.Errors) > 0 {
    os.Exit(1)
  }
}

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:

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 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.

Use 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/[email protected]/mod.js'
const ts = 'let test: boolean = true'
const result = await esbuild.transform(ts, { loader: 'ts' })
console.log('result:', result)
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.

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://golang.org/dl/

2. Download the source code for esbuild:

   git clone --depth 1 --branch v0.14.1 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.

Download a build

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-64/-/esbuild-darwin-64-0.14.1.tgztar xf ./esbuild-darwin-64-0.14.1.tgz./package/bin/esbuildUsage:
  esbuild [options] [entry points]

...

The native executable in the esbuild-darwin-64 package is for the macOS operating system and the x86-64 architecture. As of writing, this is the full list of native executable packages for the platforms esbuild supports:

Package name	OS	Architecture
esbuild-android-arm64	android	arm64
esbuild-darwin-64	darwin	x64
esbuild-darwin-arm64	darwin	arm64
esbuild-freebsd-64	freebsd	x64
esbuild-freebsd-arm64	freebsd	arm64
esbuild-linux-32	linux	ia32
esbuild-linux-64	linux	x64
esbuild-linux-arm	linux	arm
esbuild-linux-arm64	linux	arm64
esbuild-linux-mips64le	linux	mips64el
esbuild-linux-ppc64le	linux	ppc64
esbuild-netbsd-64	netbsd	x64
esbuild-openbsd-64	openbsd	x64
esbuild-sunos-64	sunos	x64
esbuild-windows-32	win32	ia32
esbuild-windows-64	win32	x64
esbuild-windows-arm64	win32	arm64

Why this is not recommended: This relies 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 since packages published to npm are immutable. An additional drawback is that you cannot use plugins with the native version.