From 45a1742c1307bdecdc86f971a71f73e9c1816b2b Mon Sep 17 00:00:00 2001 From: porhkz Date: Wed, 18 Dec 2024 16:20:16 +1030 Subject: [PATCH 1/6] Created README for esbuild --- packages/esbuild/README.md | 55 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 packages/esbuild/README.md diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md new file mode 100644 index 00000000..5ba6b6b2 --- /dev/null +++ b/packages/esbuild/README.md @@ -0,0 +1,55 @@ +# ESbuild +This repository provides a construct which runs the esbuild bundler for AWS through the ILocalBundling interface and allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output + +## Overview + +## Usage and PrerenderFargateOptions +### `loglevels` (string) +Options for the level of silence for esbuild warnings and/or error messages to the terminal + +- **silent**: (no logs outputted) +- **error**: (only shows errors) +- **warning**: (show warnings and errors) +- **info**: (show warnings, errors and an output file summary) +- **debug**: (log everything from `info` and some additional messages that may help you debug a broken handler) + +Default: **info** + +### `sourcemap` (boolean) +Source maps encode the information necessary to translate from a line/column offset in a generate output file back to a line/column offset in the corresponding original input file. Supported for both Javascript and CSS + +- **true (linked)** +(source map generated into seperate `.js.map` output file and `.js` contains special `//# sourceMappingURL =` comment that points to the `.js.map` output file) +- **external** +(source map generated into seperate `.js.map` output file and `.js` does not contain special `//# sourceMappingURL =` comment) +- **inline** +(source map appended to the end of the `.js` output file as a base64 payload inside a `//# sourceMappingURL =` comment. no `.js.map` file is generated) +- **both** +(combination of `inline` and `external`. The source map is appended inline to the end of the .js output file, and another copy of the same source map is written to a separate .js.map output file alongside the .js output file) + +Default: **true** + +### `bundle` (boolean) +Inline any imported dependecies into the file itself. Process if recursive so dependecies of dependecies (and so on) will also be inline. **Must be explictly enable** + +Default: **false** + +### `minify` (booleans) +Generated code will be minified instead of pretty-printed. Downloads faster, but harder to debug. Use minified codes in production but not in development. + +`minify` can be broken down into: +- `minifyWhitespace` +- `minifyIdentifiers` +- `minifySyntax` + +Default: **false** + +### `platform` (string) +Which platform esbuild's bundler will generate code for/ + +- **browser** +- **node** +- **neutral** + +Default: **browser** + From 9e808888933f5f5613b0fe4bf3d6166262cb3203 Mon Sep 17 00:00:00 2001 From: porhkz Date: Thu, 19 Dec 2024 09:07:05 +1030 Subject: [PATCH 2/6] Completed remaining options --- packages/esbuild/README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md index 5ba6b6b2..b62a6282 100644 --- a/packages/esbuild/README.md +++ b/packages/esbuild/README.md @@ -1,9 +1,10 @@ # ESbuild -This repository provides a construct which runs the esbuild bundler for AWS through the ILocalBundling interface and allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output +Esbuild is a module bundler and minifier for JavaScript and CSS. ## Overview +This repository provides a construct which runs the esbuild bundler for AWS through the ILocalBundling interface and allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output -## Usage and PrerenderFargateOptions +## Usage and Default esbuild options ### `loglevels` (string) Options for the level of silence for esbuild warnings and/or error messages to the terminal @@ -37,13 +38,17 @@ Default: **false** ### `minify` (booleans) Generated code will be minified instead of pretty-printed. Downloads faster, but harder to debug. Use minified codes in production but not in development. -`minify` can be broken down into: -- `minifyWhitespace` -- `minifyIdentifiers` -- `minifySyntax` - Default: **false** +`minify` can be broken down into: +- `minifyWhitespace` (boolean) + - Default: **true** +- `minifyIdentifiers` (boolean) + - Do not _minify_ identifiers. Exported 'handler' function name gets minified failing to start the lambda + - Default: **false** +- `minifySyntax` (boolean) + - Default: **true** + ### `platform` (string) Which platform esbuild's bundler will generate code for/ From 29028fa695685149504306c4181bebdd31040886 Mon Sep 17 00:00:00 2001 From: porhkz Date: Thu, 19 Dec 2024 10:56:28 +1030 Subject: [PATCH 3/6] Added shield.io badges --- packages/esbuild/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md index b62a6282..9c0ff1e6 100644 --- a/packages/esbuild/README.md +++ b/packages/esbuild/README.md @@ -1,9 +1,15 @@ # ESbuild Esbuild is a module bundler and minifier for JavaScript and CSS. + + ## Overview This repository provides a construct which runs the esbuild bundler for AWS through the ILocalBundling interface and allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output +![TypeScript version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/typescript?filename=packages/esbuild/package.json&color=red) ![AWS CDK version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/aws-cdk?filename=packages/esbuild/package.json) ![NPM version](https://img.shields.io/npm/v/%40aligent%2Fcdk-esbuild?color=green) + +# CDK Constructs: Esbuild Package + ## Usage and Default esbuild options ### `loglevels` (string) Options for the level of silence for esbuild warnings and/or error messages to the terminal From 71677c89bb6a4dc99c40ad5ddfc3cb722fd46f39 Mon Sep 17 00:00:00 2001 From: porhkz Date: Thu, 19 Dec 2024 11:20:32 +1030 Subject: [PATCH 4/6] Example added --- packages/esbuild/README.md | 49 ++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md index 9c0ff1e6..6c14ac73 100644 --- a/packages/esbuild/README.md +++ b/packages/esbuild/README.md @@ -1,15 +1,11 @@ -# ESbuild +# ESbuild Esbuild is a module bundler and minifier for JavaScript and CSS. - - ## Overview This repository provides a construct which runs the esbuild bundler for AWS through the ILocalBundling interface and allows AWS CDK's bundling process to use the esbuild tool to generate a bundled output ![TypeScript version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/typescript?filename=packages/esbuild/package.json&color=red) ![AWS CDK version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/aws-cdk?filename=packages/esbuild/package.json) ![NPM version](https://img.shields.io/npm/v/%40aligent%2Fcdk-esbuild?color=green) -# CDK Constructs: Esbuild Package - ## Usage and Default esbuild options ### `loglevels` (string) Options for the level of silence for esbuild warnings and/or error messages to the terminal @@ -64,3 +60,46 @@ Which platform esbuild's bundler will generate code for/ Default: **browser** +## Example + +``` +import { join } from "path"; +import { AssetHashType, DockerImage } from "aws-cdk-lib"; +import { Code, Runtime, Version } from "aws-cdk-lib/aws-lambda"; +import { Construct } from "constructs"; +import { Esbuild } from "@aligent/cdk-esbuild"; + +export class ExampleFunction extends Construct { + constructor(scope: Construct, id: string) { + super(scope, id); + + const command = ["sh", "-c", 'echo "Docker build not supported. Please install esbuild."']; + + new Code(this, "example-function", { + code: Code.fromAsset(join(__dirname, "handlers"), { + assetHashType: AssetHashType.OUTPUT, + bundling: { + command, + image: DockerImage.fromRegistry("busybox"), + local: new Esbuild({ + entryPoints: [join(__dirname, "handlers/example.ts")], + define: { + "process.env.EXAMPLE_VAR": "exampleValue", + }, + }), + }, + }), + runtime: Runtime.NODEJS_18_X, + handler: "example.handler", + }); + } + + public getFunctionVersion(): Version { + return Version.fromVersionArn( + this, + "example-function-version", + this.exampleFunction.currentVersion.versionArn + ); + } +} +``` From 36537e2188e6089e32fa709301533685042c810f Mon Sep 17 00:00:00 2001 From: porhkz Date: Thu, 19 Dec 2024 12:08:03 +1030 Subject: [PATCH 5/6] Edited example --- packages/esbuild/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md index 6c14ac73..dcb615ec 100644 --- a/packages/esbuild/README.md +++ b/packages/esbuild/README.md @@ -73,8 +73,6 @@ export class ExampleFunction extends Construct { constructor(scope: Construct, id: string) { super(scope, id); - const command = ["sh", "-c", 'echo "Docker build not supported. Please install esbuild."']; - new Code(this, "example-function", { code: Code.fromAsset(join(__dirname, "handlers"), { assetHashType: AssetHashType.OUTPUT, From 94d95c9490a784ccfdf377384be5e893faa0ad59 Mon Sep 17 00:00:00 2001 From: porhkz Date: Thu, 19 Dec 2024 12:28:56 +1030 Subject: [PATCH 6/6] Added required options, and more examples --- packages/esbuild/README.md | 51 ++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/packages/esbuild/README.md b/packages/esbuild/README.md index dcb615ec..0ab27273 100644 --- a/packages/esbuild/README.md +++ b/packages/esbuild/README.md @@ -6,8 +6,44 @@ This repository provides a construct which runs the esbuild bundler for AWS thro ![TypeScript version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/typescript?filename=packages/esbuild/package.json&color=red) ![AWS CDK version](https://img.shields.io/github/package-json/dependency-version/aligent/cdk-constructs/dev/aws-cdk?filename=packages/esbuild/package.json) ![NPM version](https://img.shields.io/npm/v/%40aligent%2Fcdk-esbuild?color=green) +Default options are set in [esbuild.ts](https://github.com/aligent/cdk-constructs/blob/main/packages/esbuild/esbuild.ts). Other options can be set when calling esbuild in your construct. The options listed below are some of the most common, and default options for esbuild. Remaining options can be found at [API - Esbuild](https://esbuild.github.io/api/) + ## Usage and Default esbuild options -### `loglevels` (string) +### `entryPoint` (array) +An array of files that each serve as an input to the bundling algorithm, for example: +``` +import * as esbuild from 'esbuild' + +await esbuild.build({ + entryPoints: ['home.ts', 'settings.ts'], + bundle: true, + write: true, + outdir: 'out', +}) +``` +which would create two output files, `out/home.js` and `out/settings.js`. + +More information can be found at [Entry points - Esbuild](https://esbuild.github.io/api/#entry-points:~:text=%23-,Entry%20points,-Supported%20by%3A) + +### `define` +Provides a way to replace global identifiers with constant expressions. Can change behavior of code between builds, without changing the code itself, for example: + +``` +import { join } from "path"; +import { Esbuild } from "@aligent/cdk-esbuild"; + +new Esbuild({ + entryPoints: [join(__dirname, "handlers/example.ts")], + define: { + "process.env.EXAMPLE_VAR": "\"exampleValue\"", + }, +}); +``` +where `process.env.EXAMPLE_VAR` is replace with `exampleValue` + +More information can be found at [Define - Esbuild](https://esbuild.github.io/api/#target:~:text=%23-,Define,-Supported%20by%3A) + +### `loglevels` (string, default) Options for the level of silence for esbuild warnings and/or error messages to the terminal - **silent**: (no logs outputted) @@ -18,7 +54,7 @@ Options for the level of silence for esbuild warnings and/or error messages to t Default: **info** -### `sourcemap` (boolean) +### `sourcemap` (boolean, default) Source maps encode the information necessary to translate from a line/column offset in a generate output file back to a line/column offset in the corresponding original input file. Supported for both Javascript and CSS - **true (linked)** @@ -32,12 +68,12 @@ Source maps encode the information necessary to translate from a line/column off Default: **true** -### `bundle` (boolean) +### `bundle` (boolean, default) Inline any imported dependecies into the file itself. Process if recursive so dependecies of dependecies (and so on) will also be inline. **Must be explictly enable** Default: **false** -### `minify` (booleans) +### `minify` (booleans, default) Generated code will be minified instead of pretty-printed. Downloads faster, but harder to debug. Use minified codes in production but not in development. Default: **false** @@ -51,7 +87,7 @@ Default: **false** - `minifySyntax` (boolean) - Default: **true** -### `platform` (string) +### `platform` (string, default) Which platform esbuild's bundler will generate code for/ - **browser** @@ -60,8 +96,8 @@ Which platform esbuild's bundler will generate code for/ Default: **browser** -## Example - +## Implementation Example +Derived from [GeoIP Redirect Construct CDK](https://github.com/aligent/cdk-constructs/blob/main/packages/geoip-redirect/lib/redirect-construct.ts) ``` import { join } from "path"; import { AssetHashType, DockerImage } from "aws-cdk-lib"; @@ -101,3 +137,4 @@ export class ExampleFunction extends Construct { } } ``` +