const cfFunction = new cloudfront.Function(stack, "MyFunction", { code: functionCode, runtime: cloudfront.FunctionRuntime.JS_2_0, });

### Amazon CloudWatch Synthetics: Canary monitoring

> 💡 See Monitored Website (TypeScript) for a 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:

const canary = new synthetics.Canary(stack, "MyCanary", { runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_5_1, test: synthetics.Test.custom({ code: bundledCode, handler: "index.handler", }), });

## Documentation

The package exports constructs for use with AWS CDK features.
The guiding design principal of this package is _"extend, don't replace"_.
Expect constructs that you can provide as props, not complete replacements.
For use with Lambda Functions and Synthetic Canaries, implementing lambda.Code (reference) and synthetics.Code (reference):

TypeScriptCode

Inline code is only supported by Lambda:
InlineTypeScriptCode

For use with S3 bucket deployments, implementing s3deploy.ISource (reference):
TypeScriptSource

> _Code and Source constructs seamlessly plug-in to other high-level CDK constructs. They share the same set of parameters, props and build options._
The following classes power the other features. You normally won't have to use them, but they are there if you need them:
TypeScriptAsset implements s3.Asset (reference) \
  creates an asset uploaded to S3 which can be referenced by other constructs
EsbuildBundler implements core.BundlingOptions (reference) \
  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
Auto-generated reference for Constructs, Classes and Structs.
This information is also available as part of your IDE's code completion.
Python, .NET, Go
_Esbuild_ requires a platform and architecture specific binary and currently has to be installed with a Node.js package manager like npm.
When using cdk-esbuild with Python, .NET or Go, the package will automatically detect local and global installations 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.

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.
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.

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 reference for a complete list of available methods.

// Provide an explicit path new EsbuildProvider({ esbuildModulePath: '/home/user/node_modules/esbuild/lib/main.js', });

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.

Override the default detection method
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:

### Customizing the Esbuild API

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:
Using a pre-installed version of _esbuild_ with Python, .NET or Go
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

For these scenarios, this package offers customization options and an interface to provide a custom implementation:

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_ by setting a property on EsbuildProvider.
This is the same as setting the ESBUILD_BINARY_PATH environment variable.
Defining the esbuildBinaryPath prop takes precedence.

// This will use a different esbuild binary new TypeScriptCode("src/handler.ts", { buildProvider });

#### Esbuild module path

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.

// This will use a different esbuild module new TypeScriptCode("src/handler.ts", { buildProvider });

Alternatively supported by setting the CDK_ESBUILD_MODULE_PATH environment variable, which will apply to all uses.
Defining the esbuildModulePath prop takes precedence.

If you are a Python, .NET or Go user, refer to the language specific guide for a more detailed explanation of this feature.
Custom Build and Transform API implementations
> 💡 See esbuild plugins w/ TypeScript for a working example of a custom Build API implementation.
A custom implementation can be provided by implementing IBuildProvider or ITransformProvider:

// 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.

The IBuildProvider integration with CDK relies on the outdir/outfile values and it's usually required to use them unchanged.

ITransformProvider must return the transformed code as a string.

Failures and warnings should be printed to stderr and thrown as the respective _esbuild_ error.
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.

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.
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.
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.
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 v4?

Please refer to the v5 release notes for a list of backwards incompatible changes and respective upgrade instructions.
[TS/JS] Why am I getting the error Cannot find module 'esbuild'?

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:

### [TS/JS] How can I use a different version of _esbuild_?

Use the override instructions for your package manager to force a specific version, for example:

Build and Transform interfaces are relatively stable across _esbuild_ versions.
However if any incompatibilities occur, buildOptions / transformOptions can be cast to any:

### [Python/.NET/Go] How can I use a different version of _esbuild_?

Install the desired version of _esbuild_ locally or globally as described in the documentation above.
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.

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:

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?