LinuxCommandLibrary

esbuild

Bundle JavaScript and TypeScript code quickly

TLDR

Bundle a JavaScript application and print to stdout

$ esbuild --bundle [path/to/file.js]
copy

Bundle a JSX application from stdin
$ esbuild --bundle --outfile=[path/to/out.js] < [path/to/file.jsx]
copy

Bundle and minify a JSX application with source maps in production mode
$ esbuild --bundle --define:[process.env.NODE_ENV=\"production\"] --minify --sourcemap [path/to/file.js]
copy

Bundle a JSX application for a comma-separated list of browsers
$ esbuild --bundle --minify --sourcemap --target=[chrome58,firefox57,safari11,edge16] [path/to/file.jsx]
copy

Bundle a JavaScript application for a specific node version
$ esbuild --bundle --platform=[node] --target=[node12] [path/to/file.js]
copy

Bundle a JavaScript application enabling JSX syntax in .js files
$ esbuild --bundle app.js --loader:[.js=jsx] [path/to/file.js]
copy

Bundle and serve a JavaScript application on an HTTP server
$ esbuild --bundle --serve=[port] --outfile=[index.js] [path/to/file.js]
copy

Bundle a list of files to an output directory
$ esbuild --bundle --outdir=[path/to/output_directory] [path/to/file1 path/to/file2 ...]
copy

SYNOPSIS

esbuild [options] [entry_points...]

Examples:
esbuild app.ts --bundle --outfile=bundle.js
esbuild src/index.jsx --bundle --outfile=dist/output.js --minify --target=es2017
esbuild main.ts --watch --servedir=./public --log-level=info

PARAMETERS

--bundle
    Bundles all input files and their dependencies into a single or multiple output files.

--outfile=
    Specifies the path for the primary output file. Required for single-file output.

--minify
    Enables minification of the output code, reducing its size by removing whitespace, shortening identifiers, and applying various optimizations.

--watch
    Activates watch mode, causing esbuild to rebuild the output files whenever input files change on disk.

--target=
    Sets the JavaScript language target for transpilation (e.g., es2017, chrome58, node12). This ensures compatibility with older environments.

--format=
    Defines the output bundle format (e.g., iife for immediately invoked function expressions, cjs for CommonJS, esm for ECMAScript Modules).

--sourcemap
    Generates source maps, which map the minified/bundled code back to its original source for easier debugging.

--splitting
    Enables automatic code splitting for ECMAScript Modules, allowing dynamic imports to be split into separate chunks. Requires --format=esm.

--platform=
    Specifies the platform for the output code (e.g., browser, node). Affects resolution logic and polyfills.

--external:
    Marks a specified module as external, preventing it from being bundled into the output. It will be loaded at runtime.

--loader::
    Specifies a custom loader for a given file extension (e.g., --loader:.png:dataurl to embed images as data URLs).

--define:=
    Substitutes global identifiers with specific values during the build process, often used for environment variables.

--servedir=
    Launches a development server that serves the output directory over HTTP, useful for rapid iteration and testing.

DESCRIPTION

esbuild is a powerful and exceptionally fast JavaScript/TypeScript bundler, minifier, and transpiler written in Go. Its primary design goal is speed, often outperforming older bundlers like Webpack or Rollup by 10-100x, especially for large projects.

It's engineered for rapid development cycles, significantly reducing build times and enabling quick rebuilds. esbuild supports a wide range of modern web technologies, including JSX, CSS, image assets, and more. It can be used both as a command-line interface (CLI) tool for direct invocation and through its JavaScript/Go API for integration into build systems. Key features include tree-shaking, source map generation, various output formats (IIFE, CommonJS, ESM), and basic hot module replacement capabilities.

CAVEATS

While immensely fast, esbuild's plugin ecosystem is less mature and extensive compared to older, more established bundlers like Webpack, which might limit some highly specialized transformations or integrations out-of-the-box.

It aims for speed and simplicity, so some advanced, highly configurable features found in other bundlers might require custom scripting or post-processing with esbuild.

ARCHITECTURE AND PERFORMANCE

esbuild's core is written in Go, a compiled language known for its performance and concurrency capabilities. This allows esbuild to parse, transform, and bundle JavaScript/TypeScript code significantly faster than tools written in interpreted languages or those that rely heavily on a JavaScript runtime, by utilizing multiple CPU cores efficiently.

IDEAL USE CASES

esbuild is particularly well-suited for:
1. Large-scale applications where build time is a significant bottleneck.
2. Rapid development and testing cycles in frontend projects.
3. As a foundational component in build pipelines for frameworks and libraries that prioritize performance (e.g., Vite, Next.js).
4. Projects that require a fast, low-overhead bundling solution without extensive custom configurations.

HISTORY

esbuild was created by Evan Wallace (formerly of Figma, now at Vercel) and first publicly announced in 2020. It rapidly gained prominence due to its groundbreaking speed, largely attributed to being written in Go, which allows it to leverage parallelism and low-level optimizations.

Its development has significantly influenced the broader web development toolchain, pushing other projects to prioritize build performance and encouraging innovation in the bundler space.

SEE ALSO

webpack(1), rollup(1), parcel(1), terser(1), babel(1)

Copied to clipboard