@mrgrain/cdk-esbuild 4.0.0-alpha.7 → 4.0.0-beta.0

package/CHANGELOG.md

@@ -1,4 +1,108 @@
 
+## [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)
+
+
+### Features
+
+* allow setting of esbuildBinaryPath via Construct interface ([f4eeebe](https://github.com/mrgrain/cdk-esbuild/commit/f4eeebe613bf20b8b28313a81b328bdcd1c1a8e6))
+* upgrade esbuild to support `supported` buildOption and new `copy` loader ([3ac5d92](https://github.com/mrgrain/cdk-esbuild/commit/3ac5d925342505669dbb3d3e88249f6e495b8566))
+
+
+### Bug Fixes
+
+* make TypeScriptCode and JavaScriptCode correctly extend aws_lambda.Code in jsii ([d04db27](https://github.com/mrgrain/cdk-esbuild/commit/d04db2798559b38d424a2012ebb96d14ebde4fb0))
+
 ## [3.5.0](https://github.com/mrgrain/cdk-esbuild/compare/v3.4.0...v3.5.0) (2022-06-02)
 
 

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,63 @@
-# 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) | [Migrating to v3](#migrating-to-v3) |
-[Documentation](#documentation) | [API Reference](#api-reference) | [Versioning](#versioning)
+[Getting started](#getting-started) |
+[Documentation](#documentation) | [API Reference](#api-reference) | [FAQ](#faq)
 
-> 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).
+[![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.
+This package makes _esbuild_ available to deploy AWS Lambda Functions, static websites and publish assets for use.
 
-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.
+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.
 
 **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_.
+_Esbuild_ minor version upgrades are introduced in **minor versions** of this package and inherit breaking changes from _esbuild_.
 
 ## Getting started
 
-Install `cdk-esbuild`:
+Install `cdk-esbuild` for Node.js with 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 Dotnet, use these commands:
 
-```
-npm install @mrgrain/cdk-esbuild@3 esbuild
+```sh
+# Python
+pip install streamlink-serverless
+
+# Dotnet
+dotnet add package StreamlinkServerless
 ```
 
 ### AWS Lambda: Serverless function
 
-> 💡 See [Lambda Function](examples/lambda) for a complete working example of a how to deploy a lambda function.
+> 💡 See [Lambda Function](examples/typescript/lambda) for a complete working example of a how to deploy a 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 +65,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 [Static Website with React](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,21 +87,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](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.
 >
-> ```
+> ```sh
 > npm i @aws-cdk/aws-synthetics-alpha
 > ```
 
 ```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
   },
@@ -108,7 +109,7 @@ const canary = new synthetics.Canary(stack, "MyCanary", {
   test: synthetics.Test.custom({
     code: bundledCode,
     handler: "index.handler",
-  });
+  }),
 });
 ```
 
@@ -123,7 +124,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 +139,250 @@ 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 Classes and Structs. This information is also available as part of your IDE's code completion.
+
+### Python and Dotnet
+
+Because _esbuild_ requires a platform and architecture specific binary, it currently has to be installed using npm (or any other Node.js package manager).
+
+When `cdk-esbuild` is used with Python or Dotnet, it will automatically detect a local or global installation of the _esbuild_ npm package - or fallback 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.
+
+While this "best effort" approach makes it easy to get started, it 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:
+
+- **Recommended** - Install _esbuild_ as a local package\
+  The recommended approach is to manage an additional Node.js project in the root of your AWS CDK project.
+  _esbuild_ should then be added to the `package.json` file and it is your responsibility to ensure the required setup steps are run in every environment (development machines & CI/CD systems).
+  The _esbuild_ package will then be detected automatically.
+- Install _esbuild_ as a global package\
+  Instead of installing the package in a local project, it can also be installed globally with `npm install -g esbuild` or a similar command.
+  The _esbuild_ package will be detected automatically from the global installation.
+  This approach might be preferred if a build container is prepared ahead of time, thus avoiding repeated package installation.
+- Set `CDK_ESBUILD_MODULE_PATH` env variable\
+  If an installed _esbuild_ module cannot be reliably detected by the algorithm, you can provide the absolute path to the module as an environment variable.
+  This approach has the advantage that the location of the module can be different on different systems.
+  While it can be combined with either installation approach, it is usually used with a global installation of the _esbuild_ package.
+- Set `esbuildModulePath` prop\
+  Similar to setting the module path via env variable, it can also be passed as the `esbuildModulePath` prop to a `EsbuildProvider`:
+
+  ```ts
+  new EsbuildProvider({
+    esbuildModulePath: '/home/user/node_modules/esbuild/lib/main.js'
+  });
+  ```
+
+- Override the default implementation provider\
+  Using the previous approach, but setting it for every usage:
+
+  ```ts
+  const customModule = new EsbuildProvider({
+    esbuildModulePath: '/home/user/node_modules/esbuild/lib/main.js'
+  });
+  EsbuildProvider.overrideDefaultProvider(customModule);
+  ```
+
+The `esbuildModulePath` can be provided as a known, absolute or relative path.
+When using the programmatic interface, this package additionally offers some helper methods to influence to fine-tune to automatic detection algorithm:
+
+```ts
+// This will force installation to a temporary location
+new EsbuildProvider({
+  esbuildModulePath: EsbuildSource.install()
+});
+```
+
+Please see the [`EsbuildSource`](API.md#esbuildsource) reference for a list of available methods.
 
-### Escape hatches
+### Customizing the Esbuild API
 
-It's possible that you want to use an implementation of esbuild that's different to the default one. Common reasons are:
+This package uses the _esbuild_ JavaScript API. For most use cases the default configuration will be suitable.
 
-- The current version constraints for esbuild are not suitable
+In some cases it might be useful to configure _esbuild_ differently or even provide a completely custom implementation.
+Common examples for this are:
+
+- To use a pre-installed version of _esbuild_ with Python and Dotnet
+- 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
-- Plugin support is needed for building
 
-For these situations, this package offers an escape hatch to bypass regular the implementation and provide a custom build and transform 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", {
+  transformProvider: myCustomTransformProvider,
+});
+```
 
 #### Esbuild binary path
 
-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:
+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.
 
 ```ts
-new TypeScriptCode("fixtures/handlers/ts-handler.ts", {
-  esbuildBinaryPath: "path/to/esbuild/binary"
+const buildProvider = new EsbuildProvider({
+  esbuildBinaryPath: "path/to/esbuild/binary",
 });
-```
 
-#### Custom build function
+// This will use a different esbuild binary
+new TypeScriptCode("src/handler.ts", { buildProvider });
+```
 
-> 💡 See [Using esbuild with plugins](examples/esbuild-with-plugins) for a complete working example of a custom build function using this escape hatch.
+#### Esbuild module path
 
-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.
+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
-new TypeScriptCode("fixtures/handlers/ts-handler.ts", {
-  buildFn: (options: BuildOptions): BuildResult => {
-    try {
-      // custom implementation returning BuildResult
-    } catch (error) {
-      // throw BuildFailure exception here
-    }
-  },
+const buildProvider = new EsbuildProvider({
+  esbuildModulePath: "/home/user/node_modules/esbuild/lib/main.js",
 });
+
+// This will use a different esbuild module
+new TypeScriptCode("src/handler.ts", { buildProvider });
 ```
 
-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.
+Alternatively supported by setting the `CDK_ESBUILD_MODULE_PATH` environment variable, which will apply to all uses.
+Defining the `esbuildModulePath` prop takes precedence.
 
-Failures have to cause a `BuildFailure` exception in order to be fully handled.
+#### Custom Build and Transform API implementations
 
-#### Custom transform function
+> 💡 See [Using esbuild with plugins](examples/typescript/esbuild-with-plugins) for a complete working example of a custom Build API implementation.
 
-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.
+A custom implementation can be provided by implementing `IBuildProvider` or `ITransformProvider`:
 
 ```ts
-new InlineTypeScriptCode("let x: number = 1", {
-  transformFn: (options: TransformOptions): TransformResult => {
-    try {
-      // custom implementation returning TransformResult
-    } catch (error) {
-      // throw TransformFailure exception here
+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 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 provided function will be invoked with the calculated transform options. The custom transform function can amend, change or discard any of these.
+Instead of _esbuild_, the custom methods will be invoked with all computed options.
+The custom implementation can amend, change or discard any of these.
+However with `IBuildProvider` the integration with CDK relies heavily on the `outdir`/`outfile` values and it's usually required to use them unchanged.
+`ITransformProvider` must return the transformed code as a string.
 
-Failures have to cause a `TransformFailure` exception in order to be fully handled.
+Failures and warnings should be printed to stderr and thrown as the respective _esbuild_ error.
 
-### Migrating to v3
+#### Overriding the default implementation providers
 
-The release of cdk-esbuild v3 brings compatibility with AWS CDK v2. Furthermore all deprecated properties and classes have been removed. In particular `InlineCode` classes now take `TransformerProps` as second parameter instead of transform options.
+It is also possible to change the default Esbuild API implementation for all usages of this package.
+You can change the default for both APIs or set a different implementation for each of them.
 
-#### Upgrading
+```ts
+const myCustomEsbuildProvider = new MyCustomEsbuildProvider();
 
-- 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:
+EsbuildProvider.overrideDefaultProvider(myCustomEsbuildProvider);
+EsbuildProvider.overrideDefaultBuildProvider(myCustomEsbuildProvider);
+EsbuildProvider.overrideDefaultTransformationProvider(myCustomEsbuildProvider);
 
-  ```ts
-  const oldOptions: TransformOptions = {...}
+// This will use the custom provider without the need to define it as a prop
+new TypeScriptCode("src/handler.ts");
+```
 
-  new InlineTypeScriptCode('// inline code', {
-    transformOptions: oldOptions
-  });
-  ```
+### Roadmap & Contributions
 
-## Versioning
+[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.
 
-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`.
+All contributions are welcome, no matter if they are for already planned or completely new features.
 
-### Npm Tags
+## FAQ
 
-Some users prefer to use tags over version ranges. The following stable tags are available for use:
+### How do I upgrade from `@mrgrain/cdk-esbuild` v3?
 
-- `cdk-v1`, `cdk-v2` are provided for the latest release compatible with each version of the AWS CDK.
+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.
 
-- `latest` is the most recent stable release.
+### [TS/JS] Why am I getting the error `Cannot find module 'esbuild'`?
 
-These tags also exist, but usage is strongly not recommended:
+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:
 
-- `unstable`, `next` are used for pre-release of the current and next major version respectively.
+```console
+npm install esbuild
+```
 
-- ~~`cdk-1.x.x`~~ tags have been deprecated in favour of `cdk-v1`. Use that one instead.
+### [TS/JS] How can I use a different version of _esbuild_?
 
-## Roadmap & Contributions
+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:
 
-[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.
+```json
+{
+  "overrides": {
+    "esbuild": "0.14.7"
+  }
+}
+```
 
-All contributions are welcome, no matter if they are for already planned or completely new features.
+Build and Transform interfaces are relatively stable across _esbuild_ versions.
+However if any incompatibilities occur, `buildOptions` / `transformOptions` can be cast to `any`:
+
+```ts
+const bundledCode = new TypeScriptCode("src/handler.ts", {
+  buildOptions: {
+    unsupportedOption: "value"
+  } as any,
+});
+```
 
-## Library authors
+### [Python/Dotnet] How can I use a different version of _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):
+Install the desired version of _esbuild_ locally or globally [as described in the documentation above](#python-and-dotnet).
 
-```ts
-// file: project/src/index.ts
+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
      */
@@ -27,9 +38,13 @@ export interface AssetProps extends AssetBaseProps {
 declare type JavaScriptAssetProps = AssetProps;
 declare type TypeScriptAssetProps = AssetProps;
 /**
- * @stability stable
+ * Represents a generic esbuild asset.
+ *
+ * You should always use `TypeScriptAsset` or `JavaScriptAsset`.
+ *
+ * @stability experimental
  */
-export declare abstract class Asset<Props extends AssetProps> extends S3Asset {
+export declare class EsbuildAsset<Props extends AssetProps> extends S3Asset {
     /**
      * @stability stable
      */
@@ -42,7 +57,7 @@ export declare abstract class Asset<Props extends AssetProps> extends S3Asset {
  *
  * @stability stable
  */
-export declare class JavaScriptAsset extends Asset<JavaScriptAssetProps> {
+export declare class JavaScriptAsset extends EsbuildAsset<JavaScriptAssetProps> {
 }
 /**
  * Bundles the entry points and creates a CDK asset which is uploaded to the bootstrapped CDK S3 bucket during deployment.
@@ -51,6 +66,6 @@ export declare class JavaScriptAsset extends Asset<JavaScriptAssetProps> {
  *
  * @stability stable
  */
-export declare class TypeScriptAsset extends Asset<TypeScriptAssetProps> {
+export declare class TypeScriptAsset extends EsbuildAsset<TypeScriptAssetProps> {
 }
 export {};