feat: support overriding the default esbuild API implementations (#313)

src/bundler.ts

@@ -168,7 +168,7 @@ export class EsbuildBundler {
         }
 
         try {
-          const provider = props.buildProvider ?? new EsbuildProvider();
+          const provider = props.buildProvider ?? EsbuildProvider.defaultBuildProvider();
 
           provider.buildSync({
             entryPoints: typeof entryPoints === 'string' ? [entryPoints] : entryPoints,

src/index.ts

@@ -34,11 +34,12 @@ export {
 } from './inline-code';
 
 export {
-  IBuildProvider,
-  ITransformProvider,
   EsbuildProvider,
   EsbuildProviderProps,
   EsbuildSource,
+  IBuildProvider,
+  IEsbuildProvider,
+  ITransformProvider,
   ProviderBuildOptions,
   ProviderTransformOptions,
 } from './provider';

src/inline-code.ts

@@ -43,7 +43,7 @@ abstract class BaseInlineCode extends InlineCode {
     this.inlineCode = Lazy.string({
       produce: () => {
         try {
-          const provider = props.transformProvider ?? new EsbuildProvider();
+          const provider = props.transformProvider ?? EsbuildProvider.defaultTransformationProvider();
 
           const transformedCode = provider.transformSync(code, {
             color: process.env.NO_COLOR ? Boolean(process.env.NO_COLOR) : undefined,

src/private/esbuild-source.ts

@@ -10,65 +10,50 @@ export const Esbuild = {
 
 export class EsbuildSource {
   private static dynamicPackage = dynamicEsbuild;
-  private static _default?: string;
 
   /**
-   * Set the default mechanism to find the module
+   * `EsbuildSource.nodeJs()` for NodeJs, `EsbuildSource.auto()` for all other languages
    */
-  public static set default(path: string | undefined) {
-    this._default = path;
-  }
-
-  /**
-   * The current default to find the module
-   */
-  public static get default(): string | undefined {
-    return this._default ?? this.platformDefault;
-  }
-
-  /**
-   * `EsbuildSource.nodeJs` for NodeJs, `EsbuildSource.auto` for all other languages
-   */
-  public static get platformDefault() {
+  public static platformDefault() {
     if (Boolean(process.env.JSII_AGENT)) {
-      return this.auto;
+      return this.auto();
     }
 
-    return this.nodeJs;
+    return this.nodeJs();
   }
 
   /**
    * Try to find the module in most common paths.
    */
-  public static get anywhere() {
+  public static anywhere() {
     return this.dynamicPackage.findInPaths();
   }
 
   /**
    * Try to find the module in common global installation paths.
    */
-  public static get globalPaths() {
+  public static globalPaths() {
     return this.dynamicPackage.findInGlobalPaths();
   }
 
   /**
    * Require module by name, do not attempt to find it anywhere else.
    */
-  public static get nodeJs() {
+  public static nodeJs() {
     return this.dynamicPackage.nodeJs();
   }
 
   /**
    * Install the module to a temporary location.
    */
-  public static get install() {
+  public static install() {
     return this.dynamicPackage.install();
   }
 
   /**
    * First try to find to module, then install it to a temporary location.
    */
-  public static get auto() {
+  public static auto() {
     return this.dynamicPackage.auto();
   }
 }

src/provider.ts

@@ -11,8 +11,7 @@ export interface ProviderBuildOptions extends BuildOptions {
   readonly entryPoints?: string[] | Record<string, string>;
 }
 
-export interface ProviderTransformOptions extends TransformOptions {
-}
+export interface ProviderTransformOptions extends TransformOptions {}
 
 
 /**
@@ -50,6 +49,11 @@ export interface ITransformProvider {
   transformSync(input: string, options?: ProviderTransformOptions): string;
 }
 
+/**
+ * Provides an implementation of the esbuild Build & Transform API
+ */
+export interface IEsbuildProvider extends IBuildProvider, ITransformProvider {}
+
 /**
  * Configure the default EsbuildProvider
  */
@@ -89,6 +93,46 @@ export interface EsbuildProviderProps {
  * Default esbuild implementation calling esbuild's JavaScript API.
  */
 export class EsbuildProvider implements IBuildProvider, ITransformProvider {
+  private static _fallbackProvider = new EsbuildProvider();
+  private static _buildProvider: IBuildProvider;
+  private static _transformationProvider: ITransformProvider;
+
+  /**
+   * Set the default implementation for both Build and Transformation API
+   */
+  public static overrideDefaultProvider(provider: IEsbuildProvider) {
+    this.overrideDefaultBuildProvider(provider);
+    this.overrideDefaultTransformationProvider(provider);
+  }
+
+  /**
+   * Set the default implementation for the Build API
+   */
+  public static overrideDefaultBuildProvider(provider: IBuildProvider) {
+    this._buildProvider = provider;
+  }
+
+  /**
+   * Get the default implementation for the Build API
+   */
+  public static defaultBuildProvider(): IBuildProvider {
+    return this._buildProvider ?? this._fallbackProvider;
+  }
+
+  /**
+   * Set the default implementation for the Transformation API
+   */
+  public static overrideDefaultTransformationProvider(provider: ITransformProvider) {
+    this._transformationProvider = provider;
+  }
+
+  /**
+   * Get the default implementation for the Transformation API
+   */
+  public static defaultTransformationProvider(): ITransformProvider {
+    return this._transformationProvider ?? this._fallbackProvider;
+  }
+
   private readonly esbuildBinaryPath?: string;
   private readonly esbuildModulePath?: string;
 
@@ -144,7 +188,7 @@ export class EsbuildProvider implements IBuildProvider, ITransformProvider {
    * Load the esbuild module according to defined rules.
    */
   private require(path?: string): IBuildProvider & ITransformProvider {
-    const module = path || process.env.CDK_ESBUILD_MODULE_PATH || EsbuildSource.default || Esbuild.name;
+    const module = path || process.env.CDK_ESBUILD_MODULE_PATH || EsbuildSource.platformDefault() || Esbuild.name;
 
     return this._require(this.resolve(module));
   }