npm package: @nona-creative/aws-cdk-standard-cloudfront-lambdas
Description: AWS CDK Construct for the standard edge lambda functions you are likely to need. Provides index documents and http basic auth.
Author: Nona Creative
Latest version: 2.0.1200

# aws-cdk-standard-cloudfront-lambdas

This package supplies a CDK construct that creates viewer-request and origin-request edge lambdas in us-east-1, implementing useful standard features, specifically:

- Root index documents, useful if you are hosting your site in a non public S3 bucket
- HTTP basic authentication
- Image resizing and conversion to efficient formats (webp, avif) if the browser supports them

## Versioning

The minor version of the package is synchronized to the CDK version used.

## Prerequisites

- An AWS account and relevant profile configured
- A CloudFront distribution to attach the lambdas to
- An S3 bucket to read images from and save converted images to

## WebP and Avif

If these are enabled in the configuration, they will be generated, cached, and returned for browsers that support them. If desired, quality for these formats can be specified in the query string with `wq` and `aq` parameters.

## Image resizing

- Desired width and height are specified in the query string with `w` and `h` parameters.
- Either one can or both be ommitted.
- If specifying both width and height, cropping can be selected with `c`. Default is no cropping.
- Images will not be scaled larger, so if a size larger than an image is requested, the original image size will be returned.
- Allowed dimensions can be specified to override defaults. Specifying 0 for a dimension allows that dimension to be ommitted.
- Quality for jpeg or png resizes can be specified with `jq` or `pq` parameters

## Example usage

```js
new AWSStandardCloudFrontLambdas(this, 'CloudfrontLambdas', {
  defaultRootObject: 'index.html',
  basicAuthentication: {
    user: 'aUser',
    password: 'hunter2',
  },
  imageProcessing: {
    enableResize: true,
    enableWebP: true,
    enableAvif: true,
    processedImageBasePath: 'convert',
    originBucketName: 'aBucket',
  },
  stackId: 'my-edge-stack',
})

const bucket = new Bucket(this, 'S3CloudFrontSiteBucket', { bucketName: 'nona.digital' })
const originAccessIdentity = new OriginAccessIdentity(this, 'S3CloudFrontWebsiteOAI')
bucket.grantRead(originAccessIdentity)
new CloudFrontWebDistribution(this, 'distribution', {
  originConfigs: [
    {
      s3OriginSource: {
        s3BucketSource: bucket,
        originAccessIdentity,
      },
      // Some origin e.g. S3
      behaviors: [
        {
          isDefaultBehavior: true,
          lambdaFunctionAssociations: this.awsStandardCloudFrontLambdas.lambdaFunctionAssociations,
        },
      ],
    },
  ],
})

this.awsStandardCloudFrontLambdas.grantBucketRights(bucket)
```

## Notes

- You need to have the correct AWS_PROFILE environment variable set, as the `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are picked up from the `AWS_PROFILE` environment variable
- If you use this construct in a stack deploying anywhere except us-east-1, an additional stack for your edge lambdas will be created in us-east-1
- You will need to have us-east-1 cdk bootstrapped
- As per the example above, you will need to grant the origin response lambda read and write access to the bucket your images are served from

See [example app](packages/aws-cdk-standard-cloudfront-lambdas/src/example/app.ts) for a complete example

## Gotcha

- You need to run `npm run code:build` for unit tests to work locally