README

@vanportal/serverless

Serverless with our list of supported plugins.

Serverless Plugins

To enable plugins, update serverless.yml

...
plugins:
- serverless-api-cloudfront
- serverless-apig-s3
- serverless-domain-manager
- serverless-dynamodb-local
...

Add only those you needed otherwise Serverless may complain about your configs.

About serverless-domain-manager and CNAME

Note that your CNAME records pointing to the custom domain will not work if your are using API Gateway with edge optimization setup. This is caused by the default CloudFront distribution setup in front of your endpoints.

To allow CloudFront to recognize custom domains, you will have to add "alternate domain names". But it is a no-go since since the setup is read-only. In result, CloudFront denies those CNAME requests, which do not have a Host header specifying the original resource, with a 403 Forbidden error.

If you really needed CNAME to work with edge optimization setup, you may try:
Using Page Rules to Re-Write Host Headers – Cloudflare Support.

Otherwise use regional setup.

Please also remember to remove the API gateway custom domain setup before you npx van serverless remove:

aws apigateway delete-domain-name --domain-name $(npx van sls print | npx js-yaml | jq -r '.custom.customDomain.domainName')

Available Plugins

serverless-api-cloudfront

Create and manage CloudFront distributions for API Gateway endpoints.

Automatically creates properly configured AWS CloudFront distribution that routes traffic to API Gateway.
# add in your serverless.yml

plugins:
  - serverless-api-cloudfront

custom:
  apiCloudFront:
    domain: my-custom-domain.com
    certificate: arn:aws:acm:us-east-1:000000000000:certificate/00000000-1111-2222-3333-444444444444
    waf: 00000000-0000-0000-0000-000000000000
    compress: true
    logging:
      bucket: my-bucket.s3.amazonaws.com
      prefix: my-prefix
    cookies: none
    headers:
      - x-api-key
    querystring:
      - page
      - per_page
Configuration

All apiCloudFront configuration parameters are optional - e.g. don't provide ACM Certificate ARN to use default CloudFront certificate (which works only for default cloudfront.net domain).

This plugin does not set-up automatically Route53 for newly created CloudFront distribution. After creating CloudFront distribution, manually add Route53 ALIAS record pointing to your CloudFront domain name.

First deployment may be quite long (e.g. 10 min) as Serverless is waiting for CloudFormation to deploy CloudFront distribution.

serverless-apig-s3

Create and manage API Gateway endpoints to serve static assets from S3 without coding.

This Serverless plugin automates the process of both configuring AWS to serve static front-end content and deploying your client-side bundle.

It creates an S3 bucket to hold your front-end content, and adds two routes to API Gateway:

GET / => bucket/index.html

GET /assets/* => bucket/*

This allows your API and front-end assets to be served from the same domain, sidestepping any CORS issues. CloudFront is also not used. The combination of these two properties makes this plugin a good fit for a dev stage environment.

Configuration

serverless.yml:
plugins:
 - serverless-apig-s3

custom:
  apigs3:
    dist: client/dist    # path within service to find content to upload (default: client/dist)
    dotFiles: true       # include files beginning with a dot in resources and uploads (default: false)
    topFiles: true       # create routes for top-level files in dist folder (default: false)
    resourceName: static # route path for static assets (default: assets)
    resourcePath: /dist  # path prefix for assets in s3 bucket (default: '')
Usage
sls deploy    # ensure that sls deploy has been run so that this plugin's resources exist.
sls client deploy    # uploads client build artifacts to s3

serverless-domain-manager

Create and manage domain and path mappings for lambda functions.

Create custom domain names that your lambda can deploy to with serverless. Allows for base path mapping when deploying and deletion of domain names.

Add the plugin configuration (example for serverless.foo.com/api).
custom:
  customDomain:
    domainName: serverless.foo.com
    stage: ci
    basePath: api
    certificateName: *.foo.com
    createRoute53Record: true
    endpointType: 'regional'

serverless-dynamodb-local

DynamoDB for your development environment.

Install DynamoDB Local
Start DynamoDB Local with all the parameters supported (e.g port, inMemory, sharedDb)
Table Creation for DynamoDB Local

Start: sls dynamodb start

All CLI options are optional:

--port        -p  Port to listen on. Default: 8000
--cors                    -c  Enable CORS support (cross-origin resource sharing) for JavaScript. You must provide a comma-separated "allow" list of specific domains. The default setting for -cors is an asterisk (*), which allows public access.
--inMemory                -i  DynamoDB; will run in memory, instead of using a database file. When you stop DynamoDB;, none of the data will be saved. Note that you cannot specify both -dbPath and -inMemory at once.
--dbPath                  -d  The directory where DynamoDB will write its database file. If you do not specify this option, the file will be written to the current directory. Note that you cannot specify both -dbPath and -inMemory at once. For the path, current working directory is <projectroot>/node_modules/serverless-dynamodb-local/dynamob. For example to create <projectroot>/node_modules/serverless-dynamodb-local/dynamob/<mypath> you should specify -d <mypath>/ or --dbPath <mypath>/ with a forwardslash at the end.
--sharedDb                -h  DynamoDB will use a single database file, instead of using separate files for each credential and region. If you specify -sharedDb, all DynamoDB clients will interact with the same set of tables regardless of their region and credential configuration.
--delayTransientStatuses  -t  Causes DynamoDB to introduce delays for certain operations. DynamoDB can perform some tasks almost instantaneously, such as create/update/delete operations on tables and indexes; however, the actual DynamoDB service requires more time for these tasks. Setting this parameter helps DynamoDB simulate the behavior of the Amazon DynamoDB web service more closely. (Currently, this parameter introduces delays only for global secondary indexes that are in either CREATING or DELETING status.)
--optimizeDbBeforeStartup -o  Optimizes the underlying database tables before starting up DynamoDB on your computer. You must also specify -dbPath when you use this parameter.
--migrate                 -m  After starting DynamoDB local, create DynamoDB tables from the Serverless configuration.
--seed                    -s  After starting and migrating dynamodb local, injects seed data into your tables. The --seed option determines which data categories to onload.

All the above options can be added to serverless.yml to set default configuration: e.g.

custom:
  dynamodb:
    start:
      port: 8000
      inMemory: true
      migrate: true
      seed: true
    # Uncomment only if you already have a DynamoDB running locally
    # noStart: true

@vanportal/van-serverless

Usage no npm install needed!