docs(docs): prepare documentation and examples

floydspace · floydspace · commit 27b8a73f16ee · 2020-10-27T20:15:34.000+01:00
diff --git a/README.md b/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
 ------
diff --git a/examples/complete/.gitignore b/examples/complete/.gitignore
@@ -0,0 +1,4 @@
+# CDK asset staging directory
+.cdk.staging
+cdk.out
+.build
diff --git a/examples/complete/README.md b/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.
diff --git a/examples/complete/cdk.json b/examples/complete/cdk.json
@@ -0,0 +1,4 @@
+{
+  "app": "npx ts-node stack/app.ts",
+  "versionReporting": false
+}
diff --git a/examples/complete/package.json b/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"
+  }
+}
diff --git a/examples/complete/src/index.ts b/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,
+    }),
+  };
+}
diff --git a/examples/complete/stack/app.ts b/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');
diff --git a/examples/complete/stack/stack.ts b/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']
+      }
+    });
+  }
+}
diff --git a/examples/complete/tsconfig.json b/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"]
+}
diff --git a/examples/minimal/.gitignore b/examples/minimal/.gitignore
@@ -0,0 +1,4 @@
+# CDK asset staging directory
+.cdk.staging
+cdk.out
+.build
diff --git a/examples/minimal/README.md b/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.
diff --git a/examples/minimal/cdk.json b/examples/minimal/cdk.json
@@ -0,0 +1,4 @@
+{
+  "app": "node stack/app.js",
+  "versionReporting": false
+}
diff --git a/examples/minimal/index.js b/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,
+    }),
+  };
+};
diff --git a/examples/minimal/package.json b/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"
+  }
+}
diff --git a/examples/minimal/stack/app.js b/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');
diff --git a/examples/minimal/stack/stack.js b/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 };
diff --git a/package.json b/package.json
@@ -5,6 +5,7 @@
   "license": "MIT",
   "author": "Victor Korzunin <ifloydrose@gmail.com>",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "package.json",
diff --git a/src/index.ts b/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;
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# CDK asset staging directory
 +.cdk.staging
 +cdk.out
 +.build