npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@silvermine/serverless-plugin-cloudfront-lambda-edge

v2.2.3

Published

Plugin for the SLS 1.x branch to provide support for Lambda@Edge (not currently supported by CloudFormation

Downloads

40,389

Readme

Serverless Plugin: Support CloudFront Lambda@Edge

Build Status Coverage Status Dependency Status Dev Dependency Status

What is it?

This is a plugin for the Serverless framework that adds support for associating a Lambda function with a CloudFront distribution to take advantage of the Lambda@Edge features of CloudFront.

Even though CloudFormation added support for Lambda@Edge via its LambdaFunctionAssociations config object, it would be difficult to define a CloudFront distribution in your serverless.yml file's resources that links to one of the functions that you're deploying with Serverless.

Why? Because the LambdaFunctionAssociations array needs a reference to the Lambda function's version (AWS::Lambda::Version resource), not just the function itself. (The documentation for CloudFormation says "You must specify the ARN of a function version; you can't specify a Lambda alias or $LATEST."). Serverless creates the version automatically for you, but the logical ID for it is seemingly random. You'd need that logical ID to use a Ref in your CloudFormation template for the function association.

This plugin hides all that for you - it uses other features in Serverless to be able to programmatically determine the function's logical ID and build the reference for you in the LambdaFunctionAssociations object. It directly modifies your CloudFormation template before the stack is ever deployed, so that CloudFormation does the heavy lifting for you. This 2.0 version of the plugin is thus much faster and easier to use than the 1.0 version (which existed before CloudFormation supported Lambda@Edge).

How do I use it?

There are three steps:

Install the Plugin as a Development Dependency

npm install --save-dev --save-exact @silvermine/serverless-plugin-cloudfront-lambda-edge

Telling Serverless to Use the Plugin

Simply add this plugin to the list of plugins in your serverless.yml file:

plugins:
   - '@silvermine/serverless-plugin-cloudfront-lambda-edge'

Configuring Functions to Associate With CloudFront Distributions

Also in your serverless.yml file, you will modify your function definitions to include a lambdaAtEdge property. That property can be an object if you are associating the function with only a single distribution (or single cache behavior). Or, if you want the same function associated with multiple distributions or cache behaviors, the property value can be an array of objects. Whether you define a single object or an array of objects, the objects all have the same fields, each of which is explained here:

  • distribution (required): the logical name used in your Resources section to define the CloudFront distribution.
  • eventType (required): a string, one of the four Lambda@Edge event types:
    • viewer-request
    • origin-request
    • viewer-response
    • origin-response
  • pathPattern (optional): a string, the path pattern of one of the cache behaviors in the specified distribution if you want this function to be associated with a specific cache behavior. If the path pattern is not defined here, the function will be associated with the default cache behavior for the specified distribution.
  • includeBody (optional): a boolean, true if you want to include the body in the request event your function receives. See the AWS docs for more info.

You can also apply global properties by adding the lambdaAtEdge property to your custom section of your serverless.yml. Note: This section currently only supports the follow option:

  • retain (optional): a boolean (default false). If you set this value to true, it will set the DeletionPolicy of the function resource to Retain. This can be used to avoid the currently-inevitable CloudFormation stack deletion failure. There are at least two schools of thought on how to handle this issue. Hopefully AWS will have this fixed soon. Use at your own discretion.

For example:

functions:
   directoryRootOriginRequestRewriter:
      name: '${self:custom.objectPrefix}-directory-root-origin-request-rewriter'
      handler: src/DirectoryRootOriginRequestRewriteHandler.handler
      memorySize: 128
      timeout: 1
      lambdaAtEdge:
         distribution: 'WebsiteDistribution'
         eventType: 'origin-request'

Or:

custom:
   lambdaAtEdge:
      retain: true

functions:
   someImageHandlingFunction:
      name: '${self:custom.objectPrefix}-image-handling'
      handler: src/ImageSomethingHandler.handler
      memorySize: 128
      timeout: 1
      lambdaAtEdge:
         distribution: 'WebsiteDistribution'
         eventType: 'viewer-request'
         # This must match a path pattern in a cache behavior of the distribution:
         pathPattern: 'images/*.jpg'

Or:

functions:
   someFunction:
      name: '${self:custom.objectPrefix}'
      handler: src/SomethingHandler.handler
      memorySize: 128
      timeout: 1
      lambdaAtEdge:
         -
            distribution: 'WebsiteDistribution'
            eventType: 'viewer-response'
            # This must match a path pattern in a cache behavior of the distribution:
            pathPattern: 'images/*.jpg'
         -
            distribution: 'OtherDistribution'
            eventType: 'viewer-response'

Example CloudFront Static Site Serverless Config

Here is an example of a serverless.yml file that configures an S3 bucket with a CloudFront distribution and a Lambda@Edge function:

service: static-site

custom:
   defaultRegion: us-east-1
   defaultEnvironmentGroup: dev
   region: ${opt:region, self:custom.defaultRegion}
   stage: ${opt:stage, env:USER}
   objectPrefix: '${self:service}-${self:custom.stage}'

plugins:
   - '@silvermine/serverless-plugin-cloudfront-lambda-edge'

package:
   exclude:
      - 'node_modules/**'

provider:
   name: aws
   runtime: nodejs6.10 # Because this runs on CloudFront (lambda@edge) it must be 6.10 or greater
   region: ${self:custom.region}
   stage: ${self:custom.stage}
   # Note that Lambda@Edge does not actually support environment variables for lambda
   # functions, but the plugin will strip the environment variables from any function
   # that has edge configuration on it
   environment:
      SLS_SVC_NAME: ${self:service}
      SLS_STAGE: ${self:custom.stage}

functions:
   directoryRootOriginRequestRewriter:
      name: '${self:custom.objectPrefix}-origin-request'
      handler: src/DirectoryRootOriginRequestRewriteHandler.handler
      memorySize: 128
      timeout: 1
      lambdaAtEdge:
         distribution: 'WebsiteDistribution'
         eventType: 'origin-request'

resources:
   Resources:
      WebsiteBucket:
         Type: 'AWS::S3::Bucket'
         Properties:
            BucketName: '${self:custom.objectPrefix}'
            AccessControl: 'PublicRead'
            WebsiteConfiguration:
               IndexDocument: 'index.html'
               ErrorDocument: 'error.html'
      WebsiteDistribution:
         Type: 'AWS::CloudFront::Distribution'
         Properties:
            DistributionConfig:
               DefaultCacheBehavior:
                  TargetOriginId: 'WebsiteBucketOrigin'
                  ViewerProtocolPolicy: 'redirect-to-https'
                  DefaultTTL: 600 # ten minutes
                  MaxTTL: 600 # ten minutes
                  Compress: true
                  ForwardedValues:
                     QueryString: false
                     Cookies:
                        Forward: 'none'
               DefaultRootObject: 'index.html'
               Enabled: true
               PriceClass: 'PriceClass_100'
               HttpVersion: 'http2'
               ViewerCertificate:
                  CloudFrontDefaultCertificate: true
               Origins:
                  -
                     Id: 'WebsiteBucketOrigin'
                     DomainName: { 'Fn::GetAtt': [ 'WebsiteBucket', 'DomainName' ] }
                     S3OriginConfig: {}

And here is an example function that would go with this Serverless template:

'use strict';

module.exports = {

   // invoked by CloudFront (origin requests)
   handler: function(evt, context, cb) {
      var req = evt.Records[0].cf.request;

      if (req.uri && req.uri.length && req.uri.substring(req.uri.length - 1) === '/') {
         var uri = req.uri + 'index.html';

         console.log('changing "%s" to "%s"', req.uri, uri);
         req.uri = uri;
      }

      cb(null, req);
   },

};

How do I contribute?

We genuinely appreciate external contributions. See our extensive documentation on how to contribute.

License

This software is released under the MIT license. See the license file for more details.