❗ esbuild v0.22.0 omits external packages from node bundles

[mrgrain]

With the release of esbuild v0.22.0, external node packages are by default NOT included in bundles anymore. This likely breaks most usage of esbuild with this package.

Update: v0.23.0 has been released to revert the change. We don't have a better solution for this yet, but in the meantime the recommendation is to not use v0.22.0.

Omit packages from bundles by default when targeting node (evanw/esbuild#1874, evanw/esbuild#2830, evanw/esbuild#2846, evanw/esbuild#2915, evanw/esbuild#3145, evanw/esbuild#3294, evanw/esbuild#3323, evanw/esbuild#3582, evanw/esbuild#3809, evanw/esbuild#3815)

This breaking change is an experiment. People are commonly confused when using esbuild to bundle code for node (i.e. for --platform=node) because some packages may not be intended for bundlers, and may use node-specific features that don't work with a bundler. Even though esbuild's "getting started" instructions say to use --packages=external to work around this problem, many people don't read the documentation and don't do this, and are then confused when it doesn't work. So arguably this is a bad default behavior for esbuild to have if people keep tripping over this.

With this release, esbuild will now omit packages from the bundle by default when the platform is node (i.e. the previous behavior of --packages=external is now the default in this case). Note that your dependencies must now be present on the file system when your bundle is run. If you don't want this behavior, you can do --packages=bundle to allow packages to be included in the bundle (i.e. the previous default behavior). Note that --packages=bundle doesn't mean all packages are bundled, just that packages are allowed to be bundled. You can still exclude individual packages from the bundle using --external: even when --packages=bundle is present.

The --packages= setting considers all import paths that "look like" package imports in the original source code to be package imports. Specifically import paths that don't start with a path segment of / or . or .. are considered to be package imports. The only two exceptions to this rule are subpath imports (which start with a # character) and TypeScript path remappings via paths and/or baseUrl in tsconfig.json (which are applied first).

[mrgrain]

Closing. If this changes again we will set the default to bundling in this package. Probably using version conditional defaults (see #1401)