How to bundle JavaScript files using esbuild

esbuild is an incredibly fast JavaScript bundler and minifier, designed to handle modern JavaScript, TypeScript, and more. Its performance is a game-changer, especially when dealing with large codebases. To grasp its fundamentals, one must first understand its core concepts-entry points, output formats, and build modes.

One of the primary features of esbuild is its ability to bundle multiple files into a single output, which streamlines loading in the browser. This means you can specify multiple entry points in your configuration. Here’s a simple example of how to set up a basic esbuild configuration:

const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/index.js', 'src/app.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: true,
}).catch(() => process.exit(1));

In this configuration, we define two entry points, index.js and app.js, that esbuild will bundle into a single file named bundle.js. The minify option reduces the file size by removing whitespace and comments, which is essential for production.

esbuild also supports various output formats such as CommonJS, ESM, and UMD, making it flexible for different environments. Specifying the format can be done easily:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.cjs',
  format: 'cjs',
}).catch(() => process.exit(1));

In this snippet, we create a CommonJS output. This is particularly useful for Node.js applications. When working with TypeScript, esbuild can handle the transpilation as well, allowing for seamless integration into your workflow. To enable TypeScript support, you can simply specify the entry file with a .ts extension:

esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  outfile: 'dist/main.js',
  tsconfig: 'tsconfig.json',
}).catch(() => process.exit(1));

By specifying the tsconfig option, esbuild reads your TypeScript configuration, ensuring that the build respects your compiler options. This is critical for maintaining type safety and utilizing advanced TypeScript features.

Another noteworthy aspect of esbuild is its support for plugins, which can extend its functionality. For instance, if you’re using React, you might want to add JSX support. While esbuild handles JSX out of the box, creating custom plugins can optimize your build further:

const { plugin } = require('esbuild-plugin-react');

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/react-bundle.js',
  plugins: [plugin()],
}).catch(() => process.exit(1));

This configuration adds a hypothetical React plugin to manage JSX transformations. Custom plugins can help you tailor the build process to your specific needs, whether it’s optimizing images or processing stylesheets.

Understanding how esbuild processes your code can significantly impact your development speed. With its incremental builds and hot module replacement, you can experience a more efficient development cycle. This is achieved through the watch mode:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  watch: {
    onRebuild(error, result) {
      if (error) console.error('Watch build failed:', error);
      else console.log('Watch build succeeded:', result);
    },
  },
}).catch(() => process.exit(1));

By enabling watch mode, esbuild monitors your files for changes and rebuilds automatically. This real-time feedback loop is invaluable for rapid development, allowing you to see changes almost instantly without the overhead of a full build process.

As you dive deeper into esbuild, it becomes clear that its design philosophy emphasizes speed and simplicity. Understanding these fundamentals lays the groundwork for more advanced configurations and optimizations, empowering developers to leverage its full potential. The next logical step is to explore how to configure your build process for optimal speed…

Configuring your build process for optimal speed

Speed in esbuild primarily comes from its architecture: a single binary written in Go that parallelizes work aggressively and avoids the overhead of Node.js event loops. To leverage this fully, you need to tune your build configuration with an eye toward minimizing unnecessary work and maximizing concurrency.

First, avoid overly broad entry points or glob patterns that pull in more files than necessary. Every extra file adds parsing and transformation cost. Instead, be explicit about your entry points and break your app into smaller bundles if possible. esbuild performs best when it can parallelize independent builds rather than cramming everything into one massive bundle.

Consider using the splitting option combined with format: 'esm' to enable native ES module code splitting:

esbuild.build({
  entryPoints: ['src/index.ts', 'src/admin.ts'],
  bundle: true,
  outdir: 'dist',
  splitting: true,
  format: 'esm',
  minify: true,
  sourcemap: true,
}).catch(() => process.exit(1));

This configuration tells esbuild to produce multiple output files for shared dependencies, which helps browsers cache common code chunks separately, reducing download times on subsequent visits. Note that splitting requires the output format to be ESM.

Next, controlling source maps is essential. Generating inline or external source maps can affect build speed, especially on large projects. Use sourcemap: 'external' or disable source maps entirely in production builds to speed up the process:

esbuild.build({
  entryPoints: ['src/app.ts'],
  bundle: true,
  outfile: 'dist/app.js',
  minify: true,
  sourcemap: false, // turn off source maps to speed up production builds
}).catch(() => process.exit(1));

For incremental builds during development, enable the incremental flag. This keeps esbuild’s internal cache in memory, allowing subsequent builds to be much faster. Combined with watch mode, this can transform your feedback loop:

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: true,
  incremental: true,
});

await ctx.watch();

process.on('SIGINT', async () => {
  await ctx.dispose();
  process.exit();
});

Using context API instead of build gives you more control over the lifecycle of your build and is recommended for long-running processes like dev servers.

Another speed booster is to mark large dependencies as external if you don’t want esbuild to bundle them. This reduces the work esbuild has to do, offloading dependency loading to runtime, which is often acceptable for libraries hosted on CDNs or Node.js built-ins:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  external: ['react', 'react-dom'],
}).catch(() => process.exit(1));

Here, React and ReactDOM are excluded from the bundle, expecting them to be available globally or loaded separately.

Finally, consider parallelizing builds yourself if you have multiple unrelated bundles to produce. Since esbuild runs in-process and is very fast, launching multiple builds concurrently can saturate CPU cores better than serial builds:

const builds = [
  esbuild.build({ entryPoints: ['src/admin.ts'], bundle: true, outfile: 'dist/admin.js' }),
  esbuild.build({ entryPoints: ['src/user.ts'], bundle: true, outfile: 'dist/user.js' }),
];

Promise.all(builds).catch(() => process.exit(1));

This approach is especially useful in monorepos or multi-page apps where each page has distinct dependencies.

In essence, configuring esbuild for optimal speed means balancing build size, concurrency, and caching strategies. Avoid unnecessary bundling work, leverage incremental builds during development, and tune output formats and source maps according to your deployment needs. The next challenge is to manage dependencies and external libraries effectively, which can make or break your build pipeline’s reliability and performance. Handling them requires careful consideration of how esbuild resolves modules and when to exclude or include packages explicitly. For example, you might want to alias certain imports or stub out native Node.js modules when targeting browsers…

Handling dependencies and external libraries

When working with esbuild, managing dependencies and external libraries effectively is crucial for maintaining a clean and efficient build process. The way esbuild resolves modules can impact both the speed of your builds and the size of your final output. Understanding how to handle these dependencies allows you to optimize your workflow.

By default, esbuild resolves modules based on the Node.js resolution algorithm. This means that it looks for modules in the node_modules directory and follows the package.json configuration to determine the correct entry point. However, you may encounter situations where you need to customize this behavior, such as aliasing certain imports or excluding specific libraries from the bundle.

To alias a module, you can use the alias option in your build configuration. This is particularly useful when you want to redirect imports to different versions of a library or to local files. Here’s an example:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  alias: {
    'my-library': './src/local/my-library.js',
  },
}).catch(() => process.exit(1));

In this case, any import of my-library will resolve to ./src/local/my-library.js instead of the version in node_modules. This allows for greater flexibility and control over your dependencies.

Another important aspect of handling dependencies is deciding when to mark them as external. Marking a dependency as external tells esbuild not to include it in the final bundle, which can significantly reduce the output size. This is particularly useful for libraries that are expected to be loaded from a CDN or already present in the environment. You can specify external dependencies like this:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  external: ['lodash', 'axios'],
}).catch(() => process.exit(1));

Here, both lodash and axios are excluded from the bundle, allowing you to load them separately at runtime. This can help improve load times and reduce the initial download size for users.

In addition to externalizing dependencies, you might need to handle situations where certain Node.js built-in modules are not available in a browser environment. For example, if your code relies on fs or path, you would need to provide shims or stubs for these modules. You can use the define option to create global constants that can replace these imports:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  define: {
    'process.env.NODE_ENV': '"production"',
    'fs': 'require("your-fs-shim")',
  },
}).catch(() => process.exit(1));

This configuration replaces the fs module with a custom shim that you provide, ensuring that your code can run in the browser without throwing errors due to missing modules.

Furthermore, if you are using TypeScript, you need to ensure that your type definitions align with your dependencies. When excluding external libraries, make sure to install their type definitions separately if you want to maintain type safety. This can be done using DefinitelyTyped or by installing the types directly from the library:

npm install --save-dev @types/lodash

By managing your dependencies carefully and utilizing esbuild’s configuration options, you can create a more efficient and reliable build pipeline. Understanding how to alias imports, mark dependencies as external, and provide shims for Node.js modules will empower you to optimize your projects effectively. As you refine your build setup, keep an eye out for common pitfalls and errors that may arise during this process, as they can derail your development efforts if not addressed promptly…

Troubleshooting common pitfalls and errors

Troubleshooting with esbuild often involves addressing common pitfalls that can obstruct your development workflow. One frequent issue developers encounter is misconfigured entry points. If you find that your application is not bundling correctly, double-check that the paths specified in your entry points are accurate. A simple typo or incorrect relative path can lead to frustrating build failures.

For instance, if you have the following configuration:

esbuild.build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
}).catch(() => process.exit(1));

Ensure that src/main.js exists. If it doesn’t, esbuild will throw an error, halting the build process. Always verify that your entry files are correctly referenced.

Another common issue arises with the handling of external libraries. If you’re using libraries that depend on specific global variables or environments, you may need to explicitly define them in your configuration. Failing to do so can result in runtime errors when the application attempts to access these variables:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  define: {
    'process.env.NODE_ENV': '"development"',
  },
}).catch(() => process.exit(1));

This ensures that any references to process.env.NODE_ENV in your code will resolve appropriately, preventing issues in production builds.

Dependency resolution can also cause headaches. If you notice that certain modules are not being included in your bundle, it’s worth checking the dependency tree. Use the --log-level flag during your build to gain insight into what esbuild is doing:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  logLevel: 'info',
}).catch(() => process.exit(1));

This will provide logs that can help identify missing dependencies or unresolved modules, guiding you in fixing those issues.

In some cases, you may run into issues with source maps. When they are enabled, they can sometimes lead to confusing error messages if the mapping isn’t set up correctly. If you encounter such problems, consider temporarily disabling source maps to isolate the issue:

esbuild.build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/app.js',
  sourcemap: false,
}).catch(() => process.exit(1));

Once the build is successful, you can re-enable source maps and investigate the mapping configuration if errors persist.

Another area to be cautious about is the use of plugins. When using third-party plugins, ensure they are compatible with the version of esbuild you are using. Incompatible plugins can lead to unexpected behaviors or crashes. Always refer to the plugin documentation for version compatibility:

const esbuild = require('esbuild');
const myPlugin = require('esbuild-plugin-myplugin');

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/output.js',
  plugins: [myPlugin()],
}).catch(() => process.exit(1));

Finally, if you experience performance issues or long build times, consider profiling your builds. esbuild provides options to log build times and analyze performance bottlenecks. This can help you identify which parts of your build process are slowing things down:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  logLevel: 'verbose',
}).catch(() => process.exit(1));

By systematically addressing these common pitfalls and errors, you can streamline your development process with esbuild, ensuring that your builds are efficient and reliable. The key lies in understanding the configuration options available and being vigilant about the specifics of your project setup.