docs(docs): prepare documentation and examples

Author: floydspace

README.md

@@ -31,9 +31,9 @@ Installation
 ------------
 
 ```sh
-yarn add --dev aws-lambda-nodejs-esbuild
+yarn add --dev @aws-cdk/aws-lambda aws-lambda-nodejs-esbuild
 # or
-npm install -D aws-lambda-nodejs-esbuild
+npm install -D @aws-cdk/aws-lambda aws-lambda-nodejs-esbuild
 ```
 
 
@@ -43,7 +43,21 @@ Configure
 By default, no configuration required, but you can change esbuild behavior:
 
 ```ts
-  TODO
+  import * as cdk from '@aws-cdk/core';
+  import { NodejsFunction } from 'aws-lambda-nodejs-esbuild';
+
+  class NewStack extends cdk.Stack {
+    constructor(scope, id, props) {
+      super(scope, id, props);
+
+      new NodejsFunction(this, 'NewFunction', {
+        esbuildOptions: {
+          minify: false, // default
+          target: 'ES2017', // default
+        }
+      });
+    }
+  }
 ```
 
 Check [esbuild](https://github.com/evanw/esbuild#command-line-usage) documentation for the full list of available options. Note that some options like `entryPoints` or `outdir` cannot be overwritten.
@@ -56,9 +70,11 @@ Usage
 The normal AWS CDK deploy procedure will automatically compile with `esbuild`:
 
 - Create the AWS CDK project with `cdk init app --language=typescript`
-- Install aws-lambda-nodejs-esbuild plugin as above
+- Install `aws-lambda-nodejs-esbuild` as above
 - Deploy with `cdk deploy`
 
+See examples: [minimal](examples/minimal/README.md) and [complete](examples/complete/README.md)
+
 
 Author
 ------

examples/complete/.gitignore

@@ -0,0 +1,4 @@
+# CDK asset staging directory
+.cdk.staging
+cdk.out
+.build

examples/complete/README.md

@@ -0,0 +1,7 @@
+# [aws-lambda-nodejs-esbuild](../../README.md) complete example
+
+This example shows how to use the `aws-lambda-nodejs-esbuild` construct in the most common way.
+
+Any package set as `external` in the `esbuildOptions` will not be bundled into the output file, but packed as a `node_modules` dependency.
+
+If packing a package is not required, for instance if it exists in a layer, you may set it in the option `exclude`, so it will neither be packed nor bundled. `aws-sdk` is excluded by default.

examples/complete/cdk.json

@@ -0,0 +1,4 @@
+{
+  "app": "npx ts-node stack/app.ts",
+  "versionReporting": false
+}

examples/complete/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "complete",
+  "version": "0.1.0",
+  "devDependencies": {
+    "@aws-cdk/aws-lambda": "^1.70.0",
+    "@aws-cdk/core": "^1.70.0",
+    "@types/node": "10.17.27",
+    "aws-cdk": "1.70.0",
+    "aws-lambda-nodejs-esbuild": "*",
+    "ts-node": "^8.1.0",
+    "typescript": "~3.9.7"
+  },
+  "dependencies": {
+    "isin-validator": "^1.1.1"
+  }
+}

examples/complete/src/index.ts

@@ -0,0 +1,13 @@
+import validateIsin from 'isin-validator';
+
+export function handler(event: any) {
+  const isInvalid = validateIsin(event);
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      message: isInvalid ? 'ISIN is invalid!' : 'ISIN is fine!',
+      input: event,
+    }),
+  };
+}

examples/complete/stack/app.ts

@@ -0,0 +1,5 @@
+import * as cdk from '@aws-cdk/core';
+import { CompleteStack } from './stack';
+
+const app = new cdk.App();
+new CompleteStack(app, 'CompleteStack');

examples/complete/stack/stack.ts

@@ -0,0 +1,15 @@
+import * as cdk from '@aws-cdk/core';
+import { NodejsFunction } from 'aws-lambda-nodejs-esbuild';
+
+export class CompleteStack extends cdk.Stack {
+  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
+
+    new NodejsFunction(this, 'CompleteExampleFunction', {
+      handler: 'src/index.handler',
+      esbuildOptions: {
+        external: ['isin-validator']
+      }
+    });
+  }
+}

examples/complete/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2018",
+    "module": "commonjs",
+    "lib": ["es2018"],
+    "declaration": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": false,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false,
+    "typeRoots": ["./node_modules/@types"]
+  },
+  "exclude": ["cdk.out"]
+}

examples/minimal/.gitignore

@@ -0,0 +1,4 @@
+# CDK asset staging directory
+.cdk.staging
+cdk.out
+.build

examples/minimal/README.md

@@ -0,0 +1,7 @@
+# [aws-lambda-nodejs-esbuild](../../README.md) minimal example
+
+This example shows how to use the `aws-lambda-nodejs-esbuild` construct with default options.
+
+If you do not provide a `handler` option it assumes that you define a lambda handler as `index.js` file in root folder.
+
+By default it bundles all dependencies in a single file and transpiles to the `ES2017` target.

examples/minimal/cdk.json

@@ -0,0 +1,4 @@
+{
+  "app": "node stack/app.js",
+  "versionReporting": false
+}

examples/minimal/index.js

@@ -0,0 +1,13 @@
+const validateIsin = require('isin-validator');
+
+module.exports.handler = (event) => {
+  const isInvalid = validateIsin(event);
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify({
+      message: isInvalid ? 'ISIN is invalid!' : 'ISIN is fine!',
+      input: event,
+    }),
+  };
+};

examples/minimal/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "minimal",
+  "version": "0.1.0",
+  "devDependencies": {
+    "@aws-cdk/aws-lambda": "^1.70.0",
+    "@aws-cdk/core": "1.70.0",
+    "aws-cdk": "1.70.0",
+    "aws-lambda-nodejs-esbuild": "*"
+  },
+  "dependencies": {
+    "isin-validator": "^1.1.1"
+  }
+}

examples/minimal/stack/app.js

@@ -0,0 +1,5 @@
+const cdk = require('@aws-cdk/core');
+const { MinimalStack } = require('./stack');
+
+const app = new cdk.App();
+new MinimalStack(app, 'MinimalStack');

examples/minimal/stack/stack.js

@@ -0,0 +1,12 @@
+const cdk = require('@aws-cdk/core');
+const { NodejsFunction } = require('aws-lambda-nodejs-esbuild');
+
+class MinimalStack extends cdk.Stack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+
+    new NodejsFunction(this, 'MinimalExampleFunction');
+  }
+}
+
+module.exports = { MinimalStack };

package.json

@@ -5,6 +5,7 @@
   "license": "MIT",
   "author": "Victor Korzunin <[email protected]>",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "package.json",

src/index.ts

@@ -49,7 +49,7 @@ export interface NodejsFunctionProps extends lambda.FunctionOptions {
   /**
    * The esbuild bundler specific options.
    *
-   * @default = { platform: 'node' }
+   * @default = { bundle: true, target: 'es2017' }
    */
   readonly esbuildOptions?: es.BuildOptions;
 }