feat: support setting custom esbuild module path

Fixes #218

CONTRIBUTING.md

@@ -13,14 +13,14 @@ Like every Construct, *cdk-esbuild* is a [jsii](https://github.com/aws/jsii) pro
 Sometimes it is required to test these generated packages in a real life environment.
 All paths in the instructions below, will assume you are testing with one of the examples.
 
-### NodeJs
+### Node.js
 
 **Option 1:**
 
 *This is the preferred approach, as it is more consistent and closer to how npm would behave for a real user.*
 
 - `pj build`
-- The NodeJS package can be found in `dist/js`
+- The Node.js package can be found in `dist/js`
 - In your Python app, run `npm install ../../dist/js/[email protected]` (path to the file in dist)
 - `npx cdk synth` will use the locally build version
 

src/bundler.ts

@@ -7,7 +7,7 @@ import {
   ILocalBundling,
 } from 'aws-cdk-lib';
 import { BuildOptions } from './esbuild-types';
-import { buildSync, wrapWithEsbuildBinaryPath } from './esbuild-wrapper';
+import { detectEsbuildModulePath, esbuild, wrapWithEsbuildBinaryPath } from './esbuild-wrapper';
 
 /**
  * A path or list or map of paths to the entry points of your code.
@@ -72,7 +72,7 @@ export interface BundlerProps {
    *
    * @stability stable
    */
-  readonly copyDir?: string | string[] | Record<string, string | string []>;
+  readonly copyDir?: string | string[] | Record<string, string | string[]>;
 
 
   /**
@@ -84,7 +84,7 @@ export interface BundlerProps {
    * @type esbuild.buildSync
    * @returns esbuild.BuildResult
    * @throws esbuild.BuildFailure
-   * @default esbuild.buildSync
+   * @default `esbuild.buildSync`
    */
   readonly buildFn?: any;
 
@@ -96,6 +96,23 @@ export interface BundlerProps {
    * @stability experimental
    */
   readonly esbuildBinaryPath?: string;
+
+  /**
+   * Path used to import the esbuild module.
+   *
+   * If not set, the module path will be determined in the following order:
+   *
+   * - Use a path from the `CDK_ESBUILD_MODULE_PATH` environment variable
+   * - In TypeScript, fallback to the default Node.js package resolution mechanism
+   * - All other languages (Python, Go, .NET, Java) use an automatic "best effort" resolution mechanism. \
+   *   The exact algorithm of this mechanism is considered an implementation detail and should not be relied on.
+   *   If `esbuild` cannot be found, it might be installed dynamically to a temporary location.
+   *   To opt-out of this behavior, set either `esbuildModulePath` or `CDK_ESBUILD_MODULE_PATH` env variable.
+   *
+   * @stability experimental
+   * @default - `CDK_ESBUILD_MODULE_PATH` or package resolution (see above)
+   */
+  readonly esbuildModulePath?: string;
 }
 
 /**
@@ -162,7 +179,7 @@ export class EsbuildBundler {
               this.props?.buildOptions?.absWorkingDir ?? process.cwd(),
               src,
             );
-            const destDir = resolve(outputDir, dest) ;
+            const destDir = resolve(outputDir, dest);
 
             const destToOutput = relative(outputDir, destDir);
             if (destToOutput.startsWith('..') || isAbsolute(destToOutput)) {
@@ -175,7 +192,7 @@ export class EsbuildBundler {
         }
 
         try {
-          const { buildFn = buildSync } = this.props;
+          const { buildFn = esbuild(detectEsbuildModulePath(props.esbuildModulePath)).buildSync } = this.props;
           wrapWithEsbuildBinaryPath(buildFn, this.props.esbuildBinaryPath)({
             entryPoints,
             color: process.env.NO_COLOR ? Boolean(process.env.NO_COLOR) : undefined,

src/esbuild-wrapper.ts

@@ -1,13 +1,15 @@
-/* eslint-disable import/no-extraneous-dependencies */
+import { analyzeMetafileSync, buildSync, transformSync, version } from './esbuild-types';
 
-function esbuild() {
+export function esbuild(modulePath: string = 'esbuild'): {
+  buildSync: typeof buildSync;
+  transformSync: typeof transformSync;
+  analyzeMetafileSync: typeof analyzeMetafileSync;
+  version: typeof version;
+} {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  return require('esbuild');
+  return require(modulePath);
 }
 
-export const buildSync = esbuild().buildSync;
-export const transformSync = esbuild().transformSync;
-
 export function wrapWithEsbuildBinaryPath<T extends CallableFunction>(fn: T, esbuildBinaryPath?: string) {
   if (!esbuildBinaryPath) {
     return fn;
@@ -31,4 +33,8 @@ export function wrapWithEsbuildBinaryPath<T extends CallableFunction>(fn: T, esb
 
     return result;
   };
+}
+
+export function detectEsbuildModulePath(esbuildBinaryPath?: string) {
+  return esbuildBinaryPath || process.env.CDK_ESBUILD_MODULE_PATH || 'esbuild';
 }