Can esbuild bypass top-level await transformation when targeting Node 12?

Esbuild doesn’t currently transform top-level await syntax for a target environment (like Node 12) that doesn’t support it. In other words, if you set the target to "node12" then esbuild will assume that the output code is meant to run on Node 12 (which doesn’t support top-level await) and won’t perform any transformation to change that syntax.

That means you have two options:

1. Wrap the scripts in an async function:
   Since you’re wrapping user scripts inside a function already, you can simply have the user code inside an async IIFE, for example:

   JSCopied
   (async () => {
     // user script that uses await at "top-level" (relative to this function)
     await doSomething();
   })();

   With this approach you aren’t using top-level await at the module level but rather within an async function, and Node 12 supports that.

2. Raise the target:
   If you really want the output code to use top-level await syntax directly, you’d have to set the target to at least Node 14.8 where top-level await is supported. However, this isn’t applicable to your situation if you know the code will run on Node 12.

There is an open discussion on esbuild’s GitHub regarding support for top-level await (e.g. Issue #253). Until esbuild (or another tool) implements a transformation for top-level await for unsupported targets, the only safe approach is to wrap the user script code in an async function so that all awaits are valid in Node 12.

This means that it isn’t possible to safely set the esbuild target to node12 while leaving top-level await syntax intact.