Gathering detailed insights and metrics for @mrgrain/cdk-esbuild
Gathering detailed insights and metrics for @mrgrain/cdk-esbuild
Gathering detailed insights and metrics for @mrgrain/cdk-esbuild
Gathering detailed insights and metrics for @mrgrain/cdk-esbuild
npm install @mrgrain/cdk-esbuild
Module System
Min. Node Version
Typescript Support
Node Version
NPM Version
114 Stars
1,029 Commits
8 Forks
5 Watching
6 Branches
4 Contributors
Updated on 28 Nov 2024
TypeScript (64.19%)
JavaScript (24.2%)
Python (10.15%)
Go (1.46%)
Cumulative downloads
Total Downloads
Last day
-26.7%
2,577
Compared to previous day
Last week
-11%
15,619
Compared to previous week
Last month
41.2%
74,739
Compared to previous month
Last year
165.9%
656,975
Compared to previous year
2
28
1
CDK constructs for esbuild, an extremely fast JavaScript bundler
Getting started | Documentation | API Reference | Python, .NET, & Go | FAQ
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 for AWS Lambda Functions, but the implementation cannot be used with other Constructs and doesn't expose all of esbuild's API.
Install cdk-esbuild
for Node.js using your favorite package manager:
1# npm 2npm install @mrgrain/cdk-esbuild@5 3# Yarn 4yarn add @mrgrain/cdk-esbuild@5 5# pnpm 6pnpm add @mrgrain/cdk-esbuild@5
For Python, .NET or Go, use these commands:
1# Python 2pip install mrgrain.cdk-esbuild 3 4# .NET 5dotnet add package Mrgrain.CdkEsbuild 6 7# Go 8go get github.com/mrgrain/cdk-esbuild-go/cdkesbuild/v5
💡 See Lambda (TypeScript) and Lambda (Python) for working examples of a how to deploy an AWS Lambda Function.
Use TypeScriptCode
as the code
of a lambda function:
1const bundledCode = new TypeScriptCode("src/handler.ts");
2
3const fn = new lambda.Function(stack, "MyFunction", {
4 runtime: lambda.Runtime.NODEJS_18_X,
5 handler: "index.handler",
6 code: bundledCode,
7});
💡 See React App (TypeScript) for a working example of a how to deploy a React app to S3.
Use TypeScriptSource
as one of the sources
of a static website deployment:
1const websiteBundle = new TypeScriptSource("src/index.tsx");
2
3const websiteBucket = new s3.Bucket(stack, "WebsiteBucket", {
4 autoDeleteObjects: true,
5 publicReadAccess: true,
6 removalPolicy: cdk.RemovalPolicy.DESTROY,
7 websiteIndexDocument: "index.html",
8});
9
10new s3deploy.BucketDeployment(stack, "DeployWebsite", {
11 destinationBucket: websiteBucket,
12 sources: [websiteBundle],
13});
💡 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:
1const bundledCode = new TypeScriptCode("src/canary.ts", {
2 buildOptions: {
3 outdir: "nodejs/node_modules", // This is required by AWS Synthetics
4 },
5});
6
7const canary = new synthetics.Canary(stack, "MyCanary", {
8 runtime: synthetics.Runtime.SYNTHETICS_NODEJS_PUPPETEER_5_1,
9 test: synthetics.Test.custom({
10 code: bundledCode,
11 handler: "index.handler",
12 }),
13});
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
andSource
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
Auto-generated reference for Constructs, Classes and Structs. This information is also available as part of your IDE's code completion.
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.
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.
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.
1// Use the standard Node.js algorithm to detect a locally installed package
2new EsbuildProvider({
3 esbuildModulePath: EsbuildSource.nodeJs(),
4});
5
6// Provide an explicit path
7new EsbuildProvider({
8 esbuildModulePath: '/home/user/node_modules/esbuild/lib/main.js',
9});
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.
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:
1const customModule = new EsbuildProvider({
2 esbuildModulePath: EsbuildSource.globalPaths(),
3});
4EsbuildProvider.overrideDefaultProvider(customModule);
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:
npm
, including DockerFor these scenarios, this package offers customization options and an interface to provide a custom implementation:
1declare const myCustomBuildProvider: IBuildProvider;
2
3new TypeScriptCode("src/handler.ts", {
4 buildProvider: myCustomBuildProvider,
5});
6
7
8declare const myCustomTransformProvider: ITransformProvider;
9
10new InlineTypeScriptCode("let x: number = 1", {
11 transformProvider: myCustomTransformProvider,
12});
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.
1const buildProvider = new EsbuildProvider({
2 esbuildBinaryPath: "path/to/esbuild/binary",
3});
4
5// This will use a different esbuild binary
6new TypeScriptCode("src/handler.ts", { buildProvider });
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.
1const buildProvider = new EsbuildProvider({
2 esbuildModulePath: "/home/user/node_modules/esbuild/lib/main.js",
3});
4
5// This will use a different esbuild module
6new 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.
💡 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
:
1class CustomEsbuild implements IBuildProvider, ITransformProvider {
2 buildSync(options: BuildOptions): void {
3 // custom implementation goes here
4 }
5
6 transformSync(code: string, options?: TransformOptions): string {
7 // custom implementation goes here, return transformed code
8 return 'transformed code';
9 }
10}
11
12// These will use the custom implementation
13new TypeScriptCode("src/handler.ts", {
14 buildProvider: new CustomEsbuild(),
15});
16new InlineTypeScriptCode("let x: number = 1", {
17 transformProvider: new CustomEsbuild(),
18});
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.
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.
1const myCustomEsbuildProvider = new MyCustomEsbuildProvider();
2
3EsbuildProvider.overrideDefaultProvider(myCustomEsbuildProvider);
4EsbuildProvider.overrideDefaultBuildProvider(myCustomEsbuildProvider);
5EsbuildProvider.overrideDefaultTransformationProvider(myCustomEsbuildProvider);
6
7// This will use the custom provider without the need to define it as a prop
8new TypeScriptCode("src/handler.ts");
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.
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.
cdk-esbuild
v4?Please refer to the v5 release notes for a list of backwards incompatible changes and respective upgrade instructions.
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:
1npm install esbuild
Use the override instructions for your package manager to force a specific version, for example:
1{ 2 "overrides": { 3 "esbuild": "0.14.7" 4 } 5}
Build and Transform interfaces are relatively stable across esbuild versions.
However if any incompatibilities occur, buildOptions
/ transformOptions
can be cast to any
:
1const bundledCode = new TypeScriptCode("src/handler.ts", {
2 buildOptions: {
3 unsupportedOption: "value"
4 } as any,
5});
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.
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:
1// file: node_modules/construct-library/src/index.ts 2const props = { 3 buildOptions: { 4 absWorkingDir: path.resolve(__dirname, ".."), 5 // now: /user/local-app/node_modules/construct-library 6 }, 7};
This will dynamically resolve to the correct path, wherever the package is installed. Please open an issue if you encounter any difficulties.
Yes, v2
of cdk-esbuild
is compatible with AWS CDK v1.
You can find the documentation for it on the v2 branch.
Support for AWS CDK v1 and cdk-esbuild
v2 has ended on June 1, 2023.
Both packages are not receiving any updates or bug fixes, including for security related issues.
You are strongly advised to upgrade to a supported version of these packages.
No vulnerabilities found.
Reason
30 commit(s) and 4 issue activity found in the last 90 days -- score normalized to 10
Reason
security policy file detected
Details
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
license file detected
Details
Reason
SAST tool is run on all commits
Details
Reason
detected GitHub workflow tokens with excessive permissions
Details
Reason
Found 6/12 approved changesets -- score normalized to 5
Reason
branch protection is not maximal on development and all release branches
Details
Reason
dependency not pinned by hash detected -- score normalized to 4
Details
Reason
6 existing vulnerabilities detected
Details
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
Score
Last Scanned on 2024-11-18
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More