@mrgrain/cdk-esbuild 4.0.0-alpha.8 → 4.0.0-beta.1

package/CHANGELOG.md

@@ -1,3 +1,97 @@
+
+## [4.0.0-beta.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.13.3...v4.0.0-beta.0) (2023-01-03)
+
+## [3.13.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.6...v3.13.0) (2022-12-18)
+
+
+### Features
+
+* upgrade esbuild to 0.16.0 ([#279](https://github.com/mrgrain/cdk-esbuild/issues/279)) ([20bdefa](https://github.com/mrgrain/cdk-esbuild/commit/20bdefac870d13285e4ec4e2765b493f316e2320))
+
+### [3.11.6](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.5...v3.11.6) (2022-12-17)
+
+### [3.11.5](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.4...v3.11.5) (2022-12-03)
+
+### [3.11.4](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.3...v3.11.4) (2022-11-05)
+
+### [3.11.3](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.2...v3.11.3) (2022-10-29)
+
+
+### Bug Fixes
+
+* bundler silently fails in case of an error ([#239](https://github.com/mrgrain/cdk-esbuild/issues/239)) ([3a63486](https://github.com/mrgrain/cdk-esbuild/commit/3a63486414f055e5a0b6b71bc443a649069fd034)), closes [#237](https://github.com/mrgrain/cdk-esbuild/issues/237)
+
+### [3.11.2](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.1...v3.11.2) (2022-08-24)
+
+
+### Bug Fixes
+
+* esbuild discovery can't find module installed in project ([#234](https://github.com/mrgrain/cdk-esbuild/issues/234)) ([58d7604](https://github.com/mrgrain/cdk-esbuild/commit/58d7604096fb4f7f638a873a90a714565a078d69)), closes [#233](https://github.com/mrgrain/cdk-esbuild/issues/233)
+
+### [3.11.1](https://github.com/mrgrain/cdk-esbuild/compare/v3.11.0...v3.11.1) (2022-08-22)
+
+
+### Bug Fixes
+
+* `TransformOptions.tsconfigRaw` cannot receive an object ([#230](https://github.com/mrgrain/cdk-esbuild/issues/230)) ([1584ece](https://github.com/mrgrain/cdk-esbuild/commit/1584ecedaff5251f183f08aa512151010a54df16))
+
+## [3.11.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.10.0...v3.11.0) (2022-08-20)
+
+
+### Features
+
+* auto install esbuild on jsii platforms ([#226](https://github.com/mrgrain/cdk-esbuild/issues/226)) ([d97688a](https://github.com/mrgrain/cdk-esbuild/commit/d97688a32cf62212b2756b91297c27248363619c))
+
+## [3.10.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.9.0...v3.10.0) (2022-08-14)
+
+
+### Features
+
+* support custom esbuild module path ([#220](https://github.com/mrgrain/cdk-esbuild/issues/220)) ([9cc071e](https://github.com/mrgrain/cdk-esbuild/commit/9cc071edbb8f173288ec4b68162b1bbd1f0e18c2))
+
+## [3.9.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.8.1...v3.9.0) (2022-08-14)
+
+
+### Features
+
+* lazy evaluate `InlineCode` and show message before transforming ([#217](https://github.com/mrgrain/cdk-esbuild/issues/217)) ([98f7d1d](https://github.com/mrgrain/cdk-esbuild/commit/98f7d1d23fd51967aa27c4fad62fafcb6a8cf802))
+* support NO_COLOR ([#213](https://github.com/mrgrain/cdk-esbuild/issues/213)) ([1abd267](https://github.com/mrgrain/cdk-esbuild/commit/1abd2676f9aed67f31df70dc99671bafeb9929d5)), closes [#211](https://github.com/mrgrain/cdk-esbuild/issues/211)
+* upgrade esbuild to ^0.15.0 ([#207](https://github.com/mrgrain/cdk-esbuild/issues/207)) ([7d74485](https://github.com/mrgrain/cdk-esbuild/commit/7d7448533a58a7422a2e5edb3858a74c232026d2)), closes [#204](https://github.com/mrgrain/cdk-esbuild/issues/204)
+
+### [3.8.1](https://github.com/mrgrain/cdk-esbuild/compare/v3.8.0...v3.8.1) (2022-08-13)
+
+
+### Bug Fixes
+
+* remove console object overwrites from InlineCode ([#214](https://github.com/mrgrain/cdk-esbuild/issues/214)) ([dde3fdf](https://github.com/mrgrain/cdk-esbuild/commit/dde3fdf23780c77e13e7454fb42eb2a9fda84d7e))
+
+## [3.8.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.7.2...v3.8.0) (2022-08-13)
+
+
+### Features
+
+* support new esbuild options: `platform`, `jsxDev`, `jsxImportSource` ([#209](https://github.com/mrgrain/cdk-esbuild/issues/209)) ([a7d14e7](https://github.com/mrgrain/cdk-esbuild/commit/a7d14e7bbf1655850951c3f5d041b045309b0ced))
+
+
+### Bug Fixes
+
+* `esbuildBinaryPath` not working with `Code`, not available for `InlineCode` ([#210](https://github.com/mrgrain/cdk-esbuild/issues/210)) ([dc2609b](https://github.com/mrgrain/cdk-esbuild/commit/dc2609bf48956e3bc05a1d5fdb4851672cec3883)), closes [#203](https://github.com/mrgrain/cdk-esbuild/issues/203)
+* esbuild messages printed out twice ([#212](https://github.com/mrgrain/cdk-esbuild/issues/212)) ([2596368](https://github.com/mrgrain/cdk-esbuild/commit/25963686f9f41e18af0f928e465263d1c87db611))
+
+### [3.7.2](https://github.com/mrgrain/cdk-esbuild/compare/v3.7.0...v3.7.2) (2022-07-15)
+
+
+### Bug Fixes
+
+* only reset esbuild bin path if it was overwritten ([#190](https://github.com/mrgrain/cdk-esbuild/issues/190)) ([59c3c80](https://github.com/mrgrain/cdk-esbuild/commit/59c3c80b893c2b24180f7a61757de774157779dd))
+
+## [3.7.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.6.0...v3.7.0) (2022-07-13)
+
+
+### Features
+
+* support absolute entry points, as long as they are within the working directory ([0e56b44](https://github.com/mrgrain/cdk-esbuild/commit/0e56b442a9b5c1874ee853721986f7f24d2ed455))
+
 ## [3.6.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.5.0...v3.6.0) (2022-06-23)
 
 

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2022 Moritz Kornher
+Copyright (c) 2023 Moritz Kornher
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,55 +1,57 @@
-# cdk-esbuild
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mrgrain/cdk-esbuild/main/images/wordmark-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mrgrain/cdk-esbuild/main/images/wordmark-light.svg">
+  <img src="https://raw.githubusercontent.com/mrgrain/cdk-esbuild/main/images/wordmark-dynamic.svg" alt="cdk-esbuild">
+</picture>
 
 _CDK constructs for [esbuild](https://github.com/evanw/esbuild), an extremely fast JavaScript bundler_
 
-[Getting started](#getting-started)
-[Documentation](#documentation) | [API Reference](#api-reference) | [Versioning](#versioning) | [Upgrading from AWS CDK v1](#upgrading-from-aws-cdk-v1)
+[Getting started](#getting-started) |
+[Documentation](#documentation) | [API Reference](#api-reference) | [Python & .NET](#python-and-net) | [FAQ](#faq)
 
 [![View on Construct Hub](https://constructs.dev/badge?package=%40mrgrain%2Fcdk-esbuild)](https://constructs.dev/packages/@mrgrain/cdk-esbuild)
 
 ## Why?
 
-_esbuild_ is an extremely fast bundler and minifier for Typescript and JavaScript.
-This package makes _esbuild_ available to deploy lambda functions, static websites or to publish build artefacts (assets) for further use.
+_esbuild_ is an extremely fast bundler and minifier for TypeScript and JavaScript.
+This package makes _esbuild_ available to deploy AWS Lambda Functions, static websites or publish assets for further usage.
 
-AWS CDK [supports _esbuild_ with Lambda Functions](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-lambda-nodejs-readme.html). However the implementation cannot be used with any other Constructs and doesn't expose all of _esbuild_'s build interface.
-
-This package is running _esbuild_ directly in Node.js and bypasses Docker which the AWS CDK implementation uses. The approach is quicker and easier to use for Node.js users, but incompatible with other languages.
-
-**Production readiness**
-
-This package is stable and ready to be used in production, as many do. However _esbuild_ has not yet released a version 1.0.0 and its API is still in active development. Please read the guide on [esbuild's production readiness](https://esbuild.github.io/faq/#production-readiness).
-
-Notably upgrades of the _esbuild_ minimum version requirement will be introduced in **minor versions** of this package and will inherit breaking changes from _esbuild_.
+AWS CDK [supports _esbuild_ for AWS Lambda Functions](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-lambda-nodejs-readme.html), but the implementation cannot be used with other Constructs and doesn't expose all of _esbuild_'s API.
 
 ## Getting started
 
-Install `cdk-esbuild`:
+Install `cdk-esbuild` for Node.js using your favorite package manager:
 
-```
-npm install @mrgrain/cdk-esbuild@3
+```sh
+# npm 
+npm install @mrgrain/cdk-esbuild@4
+# Yarn
+yarn add @mrgrain/cdk-esbuild@4
+# pnpm
+pnpm add @mrgrain/cdk-esbuild@4
 ```
 
-If _peer_ or _optional dependencies_ are not installed automatically (e.g. when using npm v4-6), please use this command to install all of them:
+For Python and .NET, use these commands:
 
-```
-npm install @mrgrain/cdk-esbuild@3 esbuild
+```sh
+# Python
+pip install mrgrain.cdk-esbuild
+
+# .NET
+dotnet add package Mrgrain.CdkEsbuild
 ```
 
 ### AWS Lambda: Serverless function
 
-> 💡 See [Lambda Function](examples/lambda) for a complete working example of a how to deploy a lambda function.
+> 💡 See [Lambda (TypeScript)](examples/typescript/lambda) and [Lambda (Python)](examples/typescript/lambda) for complete working examples of a how to deploy an AWS Lambda Function.
 
 Use `TypeScriptCode` as the `code` of a [lambda function](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#code):
 
 ```ts
-import * as lambda from "aws-cdk-lib/aws-lambda";
-import { TypeScriptCode } from "@mrgrain/cdk-esbuild";
-
-const bundledCode = new TypeScriptCode("src/index.ts");
+const bundledCode = new TypeScriptCode("src/handler.ts");
 
 const fn = new lambda.Function(stack, "MyFunction", {
-  runtime: lambda.Runtime.NODEJS_16_X,
+  runtime: lambda.Runtime.NODEJS_18_X,
   handler: "index.handler",
   code: bundledCode,
 });
@@ -57,21 +59,17 @@ const fn = new lambda.Function(stack, "MyFunction", {
 
 ### AWS S3: Static Website
 
-> 💡 See [Static Website with React](examples/website) for a complete working example of a how to deploy a React app to S3.
+> 💡 See [React App (TypeScript)](examples/typescript/website) for a complete working example of a how to deploy a React app to S3.
 
 Use `TypeScriptSource` as one of the `sources` of a [static website deployment](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-s3-deployment-readme.html#roadmap):
 
 ```ts
-import * as s3 from "aws-cdk-lib/aws-s3";
-import * as s3deploy from "aws-cdk-lib/aws-s3-deployment";
-import { TypeScriptSource } from "@mrgrain/cdk-esbuild";
-
 const websiteBundle = new TypeScriptSource("src/index.tsx");
 
 const websiteBucket = new s3.Bucket(stack, "WebsiteBucket", {
   autoDeleteObjects: true,
   publicReadAccess: true,
-  removalPolicy: RemovalPolicy.DESTROY,
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
   websiteIndexDocument: "index.html",
 });
 
@@ -83,23 +81,18 @@ new s3deploy.BucketDeployment(stack, "DeployWebsite", {
 
 ### Amazon CloudWatch Synthetics: Canary monitoring
 
-> 💡 See [Monitored Website](examples/website) for a complete working example of a deployed and monitored website.
+> 💡 See [Monitored Website (TypeScript)](examples/typescript/website) for a complete working example of a deployed and monitored website.
 
 Synthetics runs a canary to produce traffic to an application for monitoring purposes. Use `TypeScriptCode` as the `code` of a Canary test:
 
-> ℹ️ This feature depends on the `@aws-cdk/aws-synthetics-alpha` package which is a developer preview. You may need to update your source code when upgrading to a newer version of this package.
->
-> ```
-> npm i @aws-cdk/aws-synthetics-alpha
-> ```
+> ℹ️ This feature depends on `@aws-cdk/aws-synthetics-alpha` which is in developer preview.
+> Please install the package using the respective tool of your language.
+> You may need to update your source code when upgrading to a newer version of this alpha package.
 
 ```ts
-import * as synthetics from "@aws-cdk/aws-synthetics-alpha";
-import { TypeScriptCode } from "@mrgrain/cdk-esbuild";
-
-const bundledCode = new TypeScriptCode("src/index.ts", {
+const bundledCode = new TypeScriptCode("src/canary.ts", {
   buildOptions: {
-    outdir: "nodejs/node_modules", // This is required by Synthetics
+    outdir: "nodejs/node_modules", // This is required by AWS Synthetics
   },
 });
 
@@ -108,13 +101,13 @@ const canary = new synthetics.Canary(stack, "MyCanary", {
   test: synthetics.Test.custom({
     code: bundledCode,
     handler: "index.handler",
-  });
+  }),
 });
 ```
 
 ## Documentation
 
-The package exports various different constructs for use with existing CDK features. A major guiding design principal for this package is to _extend, don't replace_. Expect constructs that you can provide as props, not complete replacements.
+The package exports various different constructs for use with AWS CDK features. The guiding design principal for this package is _"extend, don't replace"_. Expect constructs that you can provide as props, not complete replacements.
 
 For use in **Lambda Functions** and **Synthetic Canaries**, the following classes implement `lambda.Code` ([reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Code.html)) and `synthetics.Code` ([reference](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-synthetics-alpha.Code.html)):
 
@@ -123,7 +116,6 @@ For use in **Lambda Functions** and **Synthetic Canaries**, the following classe
 Inline code is only supported by **Lambda**:
 
 - `InlineTypeScriptCode` & `InlineJavaScriptCode`
-- `InlineTsxCode` & `InlineJsxCode`
 
 For use with **S3 bucket deployments**, classes implementing `s3deploy.ISource` ([reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-s3-deployment-readme.html)):
 
@@ -139,129 +131,274 @@ The following classes power the other features. You normally won't have to use t
 - `EsbuildBundler` implements `core.BundlingOptions` ([reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.BundlingOptions.html)) \
   provides an interface for a _esbuild_ bundler wherever needed
 
+- `EsbuildProvider` implements `IBuildProvider` and `ITransformProvider` \
+  provides the default _esbuild_ API implementation and can be replaced with a custom implementation
+
 ### [API Reference](API.md)
 
-Auto-generated reference for classes and structs. This information is also available as part of your IDE's code completion.
+Auto-generated reference for Constructs, Classes and Structs.
+This information is also available as part of your IDE's code completion.
 
-### Escape hatches
+### Python and .NET
 
-It's possible that you want to use an implementation of esbuild that's different to the default one. Common reasons are:
+_Esbuild_ requires a platform and architecture specific binary and currently has to be installed with a Node.js package manager like npm.
 
-- The current version constraints for esbuild are not suitable
-- To use a version of esbuild that is installed by any other means than `npm`, including Docker
-- Plugin support is needed for building
+When using `cdk-esbuild` with Python or .NET, the package will automatically detect a local or global installation of the _esbuild_ npm package.If none can be found, it will fall back to dynamically installing a copy into a temporary location.
+The exact algorithm of this mechanism must be treated as an implementation detail and should not be relied on.
+It can however be configured to a certain extent.
+See the examples below for more details.
 
-For these situations, this package offers an escape hatch to bypass regular the implementation and provide a custom build and transform function.
+This "best effort" approach makes it easy to get started.
+But is not always desirable, for example in environments with limited network access or when guaranteed repeatability of builds is a concern.
+You have several options to opt-out of this behavior.
 
-#### Esbuild binary path
+#### Provide a controlled installation of _esbuild_
+
+The first step is to install a version of _esbuild_ that is controlled by you.
+
+I **strongly recommend** to install _esbuild_ as a local package.
+The easiest approach is to manage an additional Node.js project at the root of your AWS CDK project.
+_esbuild_ can then be added to the `package.json` file and it is your responsibility to ensure required setup steps are taken in all environments like development machines and CI/CD systems.
 
-It is possible to override the binary used by esbuild. The usual way to do this is to set the `ESBUILD_BINARY_PATH` environment variable. For convenience this package allows to set the binary path as a prop:
+Instead of installing the _esbuild_ package in a local project, it can also be **installed globally** with `npm install -g esbuild` or a similar command.
+This approach might be preferred if a build container is prepared ahead of time, thus avoiding repeated package installation.
+
+#### Change the automatic package detection
+
+The second step is to make `cdk-esbuild` aware of your chosen install location.
+This step is optional, but it's a good idea to have the location or at least the method explicitly defined.
+
+To do this, you can set the `esbuildModulePath` prop on a `EsbuildProvider`.
+Either pass a known, absolute or relative path as value, or use the `EsbuildSource` helper to set the detection method.
+Please refer to the [`EsbuildSource`](API.md#esbuildsource) reference for a complete list of available methods.
 
 ```ts
-new TypeScriptCode("fixtures/handlers/ts-handler.ts", {
-  esbuildBinaryPath: "path/to/esbuild/binary"
+// Use the standard Node.js algorithm to detect a locally installed package
+new EsbuildProvider({
+  esbuildModulePath: EsbuildSource.nodeJs(),
+});
+
+// Provide an explicit path
+new EsbuildProvider({
+  esbuildModulePath: '/home/user/node_modules/esbuild/lib/main.js',
 });
 ```
 
-#### Custom build function
+As a no-code approach, the `CDK_ESBUILD_MODULE_PATH` environment variable can be set in the same way.
+An advantage of this is that the path can easily be changed for different systems.
+Setting the env variable can be used with any installation approach, but is typically paired with a global installation of the _esbuild_ package.
+Note that `esbuildModulePath` takes precedence.
 
-> 💡 See [Using esbuild with plugins](examples/esbuild-with-plugins) for a complete working example of a custom build function using this escape hatch.
+#### Override the default detection method
 
-Constructs that result in starting a build, take a `buildFn` as optional prop. While the defined type for this function is `any`, it must implement the same signature as esbuild's `buildSync` function.
+For an AWS CDK app with many instances of `TypeScriptCode` etc. it would be annoying to change the above for every single one of them.
+Luckily, the default can be changed for all usages per app:
 
 ```ts
-new TypeScriptCode("fixtures/handlers/ts-handler.ts", {
-  buildFn: (options: BuildOptions): BuildResult => {
-    try {
-      // custom implementation returning BuildResult
-    } catch (error) {
-      // throw BuildFailure exception here
-    }
-  },
+const customModule = new EsbuildProvider({
+  esbuildModulePath: EsbuildSource.globalPaths(),
 });
+EsbuildProvider.overrideDefaultProvider(customModule);
 ```
 
-Instead of esbuild, the provided function will be invoked with the calculated build options. The custom build function can amend, change or discard any of these. However integration with CDK relies heavily on the values `outdir`/`outfile` are set to and it's usually required to use them unchanged.
+### Customizing the Esbuild API
 
-Failures have to cause a `BuildFailure` exception in order to be fully handled.
+This package uses the _esbuild_ JavaScript API.
+In most situations the default API configuration will be suitable.
+But sometimes it is required to configure _esbuild_ differently or even provide a custom implementation.
+Common reasons for this are:
 
-#### Custom transform function
+- Using a pre-installed version of _esbuild_ with Python or .NET
+- If features not supported by the synchronous API are required, e.g. support for plugins
+- If the default version constraints for _esbuild_ are not suitable
+- To use a version of esbuild that is installed by any other means than `npm`, including Docker
 
-Constructs that result in starting a transformation, take a `transformFn` as optional prop. While the defined type for this function is `any`, it must implement the same signature as esbuild's `transformSync` function.
+For these scenarios, this package offers customization options and an interface to provide a custom implementation:
 
 ```ts
+declare const myCustomBuildProvider: IBuildProvider;
+
+new TypeScriptCode("src/handler.ts", {
+  buildProvider: myCustomBuildProvider,
+});
+
+
+declare const myCustomTransformProvider: ITransformProvider;
+
 new InlineTypeScriptCode("let x: number = 1", {
-  transformFn: (options: TransformOptions): TransformResult => {
-    try {
-      // custom implementation returning TransformResult
-    } catch (error) {
-      // throw TransformFailure exception here
-    }
-  },,
+  transformProvider: myCustomTransformProvider,
 });
 ```
 
-Instead of esbuild, the provided function will be invoked with the calculated transform options. The custom transform function can amend, change or discard any of these.
+#### Esbuild binary path
 
-Failures have to cause a `TransformFailure` exception in order to be fully handled.
+It is possible to override the binary used by _esbuild_ by setting a property on `EsbuildProvider`.
+This is the same as setting the `ESBUILD_BINARY_PATH` environment variable.
+Defining the `esbuildBinaryPath` prop takes precedence.
 
-### Upgrading from AWS CDK v1
+```ts
+const buildProvider = new EsbuildProvider({
+  esbuildBinaryPath: "path/to/esbuild/binary",
+});
 
-This version is compatible with AWS CDK v2. For the previous, AWS CDK v1 compatible release, see [cdk-esbuild@v2](https://github.com/mrgrain/cdk-esbuild/tree/v2).
+// This will use a different esbuild binary
+new TypeScriptCode("src/handler.ts", { buildProvider });
+```
 
-To upgrade from AWS CDK v1 and cdk-esbuild@v2, please follow these steps:
+#### Esbuild module path
 
-- This version requires AWS CDK v2. Follow the [official migration guide](https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html) to upgrade.
-- Update the package dependency to v3: `npm install --save @mrgrain/cdk-esbuild@^3.0.0`
-- `esbuild` is installed as an optional dependency. If your setup does not automatically install optional dependencies, make sure to add it as an explicit dependency.
-- Any use of `InlineCode` variations has to be updated. Previously the second parameter was either of type `TransformerProps` or `TransformOptions`. Now it must be `TransformerProps`.\
-  If the passed value is of type `TransformOptions`, turn it into the correct type like this:
+The Node.js module discovery algorithm will normally be used to find the _esbuild_ package.
+It can be useful to use specify a different module path, for example if a globally installed package should be used instead of a local version.
 
-  ```ts
-  const oldOptions: TransformOptions = {...}
+```ts
+const buildProvider = new EsbuildProvider({
+  esbuildModulePath: "/home/user/node_modules/esbuild/lib/main.js",
+});
 
-  new InlineTypeScriptCode('// inline code', {
-    transformOptions: oldOptions
-  });
-  ```
+// This will use a different esbuild module
+new TypeScriptCode("src/handler.ts", { buildProvider });
+```
 
-## Versioning
+Alternatively supported by setting the `CDK_ESBUILD_MODULE_PATH` environment variable, which will apply to all uses.
+Defining the `esbuildModulePath` prop takes precedence.
 
-This package follows [Semantic Versioning](https://semver.org/), with the exception of upgrades to `esbuild`. These will be released as **minor versions** and often include breaking changes from `esbuild`.
+If you are a Python or .NET users, see the language specific guide for a more detailed expose on this feature.
 
-### Npm Tags
+#### Custom Build and Transform API implementations
 
-Some users prefer to use tags over version ranges. The following stable tags are available for use:
+> 💡 See [esbuild plugins w/ TypeScript](examples/typescript/esbuild-with-plugins) for a complete working example of a custom Build API implementation.
 
-- `cdk-v1`, `cdk-v2` are provided for the latest release compatible with each version of the AWS CDK.
+A custom implementation can be provided by implementing `IBuildProvider` or `ITransformProvider`:
 
-- `latest` is the most recent stable release.
+```ts
+class CustomEsbuild implements IBuildProvider, ITransformProvider {
+    buildSync(options: BuildOptions): void {
+      // custom implementation goes here
+    }
+  
+    transformSync(code: string, options?: TransformOptions): string {
+      // custom implementation goes here, return transformed code
+      return 'transformed code';
+    }
+}
 
-These tags also exist, but usage is strongly not recommended:
+// These will use the custom implementation
+new TypeScriptCode("src/handler.ts", {
+  buildProvider: new CustomEsbuild(),
+});
+new InlineTypeScriptCode("let x: number = 1", {
+  transformProvider: new CustomEsbuild(),
+});
+```
+
+Instead of _esbuild_, the custom methods will be invoked with all computed options.
+Custom implementations can amend, change or discard any of the options.
 
-- `unstable`, `next` are used for pre-release of the current and next major version respectively.
+The `IBuildProvider` integration with CDK relies on the `outdir`/`outfile` values and it's usually required to use them unchanged.
 
-- ~~`cdk-1.x.x`~~ tags have been deprecated in favour of `cdk-v1`. Use that one instead.
+`ITransformProvider` must return the transformed code as a string.
 
-## Roadmap & Contributions
+Failures and warnings should be printed to stderr and thrown as the respective _esbuild_ error.
 
-[The project's roadmap is available on GitHub.](https://github.com/mrgrain/cdk-esbuild/projects/1) Please submit any feature requests as issues to the repository.
+#### Overriding the default implementation providers
 
+The default implementation can also be set for all usages of `TypeScriptCode` etc. in an AWS CDK app.
+You can change the default for both APIs at once or set a different implementation for each of them.
+
+```ts
+const myCustomEsbuildProvider = new MyCustomEsbuildProvider();
+
+EsbuildProvider.overrideDefaultProvider(myCustomEsbuildProvider);
+EsbuildProvider.overrideDefaultBuildProvider(myCustomEsbuildProvider);
+EsbuildProvider.overrideDefaultTransformationProvider(myCustomEsbuildProvider);
+
+// This will use the custom provider without the need to define it as a prop
+new TypeScriptCode("src/handler.ts");
+```
+
+### Roadmap & Contributions
+
+[The project's roadmap is available on GitHub.](https://github.com/users/mrgrain/projects/1/views/7)
+
+Please submit feature requests as issues to the repository.
 All contributions are welcome, no matter if they are for already planned or completely new features.
 
-## Library authors
+## FAQ
+
+### Should I use this package in production?
+
+This package is stable and ready to be used in production, as many do.
+However _esbuild_ has not yet released a version 1.0.0 and its API is still in active development.
+Please read the guide on [esbuild's production readiness](https://esbuild.github.io/faq/#production-readiness).
+
+Note that _esbuild_ minor version upgrades are also introduced in **minor versions** of this package.
+Since _esbuild_ is pre v1, these versions typically introduce breaking changes and this package will inherit them.
+To avoid this behavior, add the desired _esbuild_ version as a dependency to your package.
+
+### How do I upgrade from `cdk-esbuild` v3?
+
+Please refer to the [v4 release notes](https://github.com/mrgrain/cdk-esbuild/releases/tag/v4.0.0) for a list of backwards incompatible changes and respective upgrade instructions.
+
+### [TS/JS] Why am I getting the error `Cannot find module 'esbuild'`?
 
-Building a library consumed by other packages that relies on `cdk-esbuild` might require you to set `buildOptions.absWorkingDir`. The easiest way to do this, is to resolve based on the directory name of the calling file, and traverse the tree upwards to the root of your library package (that's where `package.json` and `tsconfig.json` are):
+This package depends on _esbuild_ as an optional dependencies. If optional dependencies are not installed automatically on your system (e.g. when using npm v4-6), install _esbuild_ explicitly:
+
+```console
+npm install esbuild
+```
+
+### [TS/JS] How can I use a different version of _esbuild_?
+
+Use the [override](https://docs.npmjs.com/cli/v9/configuring-npm/package-json?v=true#overrides) instructions for your package manager to force a specific version, for example:
+
+```json
+{
+  "overrides": {
+    "esbuild": "0.14.7"
+  }
+}
+```
+
+Build and Transform interfaces are relatively stable across _esbuild_ versions.
+However if any incompatibilities occur, `buildOptions` / `transformOptions` can be cast to `any`:
 
 ```ts
-// file: project/src/index.ts
+const bundledCode = new TypeScriptCode("src/handler.ts", {
+  buildOptions: {
+    unsupportedOption: "value"
+  } as any,
+});
+```
+
+### [Python/.NET] How can I use a different version of _esbuild_?
+
+Install the desired version of _esbuild_ locally or globally [as described in the documentation above](#python-and-dotnet).
+
+Build and Transform interfaces are relatively stable across _esbuild_ versions.
+However if any incompatibilities occur, use the appropriate language features to cast any incompatible `buildOptions` / `transformOptions` to the correct types.
+
+### Can I use this package in my published AWS CDK Construct?
+
+It is possible to use `cdk-esbuild` in a published AWS CDK Construct library, but not recommended.
+Always prefer to ship a compiled `.js` file or even bundle a zip archive in your package.
+For AWS Lambda Functions, [projen provides an excellent solution](https://projen.io/awscdk.html#aws-lambda-functions).
+
+If you do end up consuming `cdk-esbuild`, you will have to set `buildOptions.absWorkingDir`. The easiest way to do this, is to resolve the path based on the directory name of the calling file:
+
+```js
+// file: node_modules/construct-library/src/index.ts
 const props = {
   buildOptions: {
-    absWorkingDir: path.resolve(__dirname, ".."), // now: /user/project
+    absWorkingDir: path.resolve(__dirname, ".."),
+    // now: /user/local-app/node_modules/construct-library
   },
 };
 ```
 
-This will dynamically resolve to the correct path, wherever the package is installed.
+This will dynamically resolve to the correct path, wherever the package is installed. Please open an issue if you encounter any difficulties.
+
+### Can I use this package with AWS CDK v1?
+
+Yes, the `2.x.x` line of `cdk-esbuild` is compatible with AWS CDK v1. You can find the [documentation for it on the v2 branch](https://github.com/mrgrain/cdk-esbuild/tree/v2).
 
-Please open an issue if you encounter any difficulties.
+However, in line with AWS CDK v2, this version release now only receives security updates and critical bug fixes and support will fully end on June 1, 2023.

package/lib/asset.d.ts

@@ -18,7 +18,18 @@ export interface AssetBaseProps extends BundlerProps {
 }
 export interface AssetProps extends AssetBaseProps {
     /**
-     * A relative path or list or map of relative paths to the entry points of your code from the root of the project. E.g. `src/index.ts`.
+     * A path or list or map of paths to the entry points of your code.
+     *
+     * Relative paths are by default resolved from the current working directory.
+     * To change the working directory, see `buildOptions.absWorkingDir`.
+     *
+     * Absolute paths can be used if files are part of the working directory.
+     *
+     * Examples:
+     *  - `'src/index.ts'`
+     *  - `require.resolve('./lambda')`
+     *  - `['src/index.ts', 'src/util.ts']`
+     *  - `{one: 'src/two.ts', two: 'src/one.ts'}`
      *
      * @stability stable
      */