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 { } } ``` +