feat: expose bundlerPriority to highlevel constructs, deprecate force…

…DockerBundling

README.md

@@ -156,9 +156,12 @@ Underlying classes the power the other features. You normally won't have to use
   **⚠️ Experimental** - _Likely to change once esbuild supports this natively_ \
   Relative path to a directory copied to the output before the build is run (i.e esbuild will overwrite existing files).
 
-- `props.forceDockerBundling: boolean (false)` \
+- **⚠️ Deprecated** `props.forceDockerBundling: boolean (false)` \
   Force use of Docker bundling and skip local bundling. This can be useful in CI environments. The `absWorkingDir` path (or current working directory) will be mounted into the container as context. By default bundling with a locally installed binary is preferred and Docker will only be used if the local bundling fails.
 
+- `props.bundlerPriority: BundlerPriority (BundlerPriority.AttemptLocal)` \
+  Set the priority order of available bundlers. It can be useful to limit use to one of the bundlers. For Docker, the `absWorkingDir` path (or current working directory) will be mounted into the container as context. By default bundling with a locally installed binary is attempted first and Docker will only be used if the local bundling fails.
+
 ## `TypeScriptSource`, `JavaScriptSource`
 
 > ℹ️ _Although these classes are currently identical, please use the appropriate class as functionality might diverge in future releases._
@@ -217,9 +220,12 @@ Bundles the entry points and creates a CDK asset which is uploaded to the bootst
    **⚠️ Experimental** - _Likely to change once esbuild supports this natively_ \
    Relative path to a directory copied to the output before the build is run (i.e esbuild will overwrite existing files).
 
-- `props.forceDockerBundling: boolean (false)` \
+- **⚠️ Deprecated** `props.forceDockerBundling: boolean (false)` \
   Force use of Docker bundling and skip local bundling. This can be useful in CI environments. The `absWorkingDir` path (or current working directory) will be mounted into the container as context. By default bundling with a locally installed binary is preferred and Docker will only be used if the local bundling fails.
 
+- `props.bundlerPriority: BundlerPriority (BundlerPriority.AttemptLocal)` \
+  Set the priority order of available bundlers. It can be useful to limit use to one of the bundlers. For Docker, the `absWorkingDir` path (or current working directory) will be mounted into the container as context. By default bundling with a locally installed binary is attempted first and Docker will only be used if the local bundling fails.
+
 - `props.buildOptions` as per esbuild [(reference)](https://esbuild.github.io/getting-started/#build-scripts) \
   **All build options are optional.** \
   ➡️ See `TypeScriptCode` for detailed explanation on options.

lib/asset.ts

@@ -1,7 +1,7 @@
 import { Asset as S3Asset } from "@aws-cdk/aws-s3-assets";
 import { AssetHashType, Construct, ConstructNode, IAsset } from "@aws-cdk/core";
 import { isAbsolute } from "path";
-import { BuildOptions } from "./bundlers";
+import { BuildOptions, BundlerPriority } from "./bundlers";
 import { EsbuildBundling } from "./bundling";
 export interface EsbuildAssetProps extends Partial<IAsset> {
   /**
@@ -16,9 +16,18 @@ export interface EsbuildAssetProps extends Partial<IAsset> {
 
   /**
    * Force the asset to use Docker bundling (and skip local bundling).
+   *
+   * @deprecated please use `bundlerPriority`
    */
   forceDockerBundling?: boolean;
 
+  /**
+   * Priority order of available bundlers. Defaults to attempt local first, then docker.
+   *
+   * @default BundlerPriority.AttemptLocal
+   */
+  bundlerPriority?: BundlerPriority;
+
   /**
    * Options passed on to esbuild.
    */
@@ -36,6 +45,9 @@ abstract class Asset<Props extends EsbuildAssetProps> extends S3Asset {
       entryPoints: propEntryPoints,
       assetHash,
       forceDockerBundling = false,
+      bundlerPriority = forceDockerBundling === true
+        ? BundlerPriority.DockerOnly
+        : BundlerPriority.AttemptLocal,
       copyDir,
       buildOptions: options = {},
     }: Props
@@ -71,7 +83,7 @@ abstract class Asset<Props extends EsbuildAssetProps> extends S3Asset {
           entryPoints,
         },
         {
-          localBundling: !forceDockerBundling,
+          priority: bundlerPriority,
           copyDir,
         }
       ),