esbuild

esbuild Best Practices

esbuild is the definitive choice for speed-first JavaScript/TypeScript bundling. Follow these rules to maximize its performance, maintainability, and production readiness.

1. Centralize Configuration

Always manage esbuild options in a dedicated .mjs file for clarity, reproducibility, and IDE linting. Avoid scattering CLI flags across package.json scripts.

❌ BAD

// package.json
"scripts": {
  "build": "esbuild src/index.js --bundle --minify --outfile=dist/bundle.js"
}

✅ GOOD

// esbuild.config.mjs
import * as esbuild from 'esbuild';

const isProduction = process.env.NODE_ENV === 'production';

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: isProduction,
  sourcemap: !isProduction ? 'inline' : 'external', // External sourcemaps for production debugging
  define: {
    'process.env.NODE_ENV': JSON.stringify(isProduction ? 'production' : 'development'),
  },
}).catch(() => process.exit(1));

2. Optimize for Target Environments

Specify the target to ensure esbuild only transpiles what's necessary, reducing bundle size and build time.

❌ BAD

// esbuild.config.mjs
esbuild.build({
  // ...
  // No target specified, defaults to 'esnext' which might over-transpile
});

✅ GOOD

// esbuild.config.mjs
esbuild.build({
  // ...
  target: ['es2022', 'chrome90', 'firefox90'], // Target modern browsers/Node.js versions
});

3. Leverage Incremental Builds for Development

For rapid development feedback, enable incremental builds or use watch mode.

❌ BAD

// esbuild.config.mjs (development)
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
}).catch(() => process.exit(1)); // Full rebuild on every run

✅ GOOD

// esbuild.config.mjs (development)
import * as esbuild from 'esbuild';

async function devBuild() {
  const ctx = await esbuild.context({
    entryPoints: ['src/index.js'],
    bundle: true,
    outdir: 'dist',
    sourcemap: true,
  });
  await ctx.watch(); // Near-instant rebuilds on file changes
  console.log('Watching for changes...');
}
devBuild();