mykolasmolis/serverless-frontend-plugin

Serverless plugin to automate packaging and deploying a frontend UI in AWS Cloudfront and S3

serverless-frontend-plugin

Package and deploy any frontend with your serverless backend.

Installation

npm install --save-dev serverless-frontend-plugin

Implementation

• Include this plugin in the plugins section of your severless.yml.

plugins:
  - serverless-frontend-plugin

• Add your frontend build commands and set the working directory by adding the following to the custom section of your serverless.yml:

custom:
  serverless-frontend-plugin:
    distDir: frontend/dist
    build:
      cwdDir: frontend
      command:
        - npm
        - run
        - build
    distribution:
      acmCertificateArn: <your certificate arn>
      dnsName: <your-domain.com> # Route53 record value
      altDnsName: <another.your-domain.com> # Route53 record value
      hostedZoneName: <your-domain.com> # Route53 Hosted Zone Name

Options

• mode: (string) Type of frontend hosting. Currently the only supported mode is cloudfront.
• distDir: (string) The directory that gets uploaded and hosted as a static site. Defaults to frontend/dist.
• build: (Map)
  • command: (string[]) Command and options as an array of strings. For example, ["npm", "run", "build"] Defaults to ["echo", "no", "frontend", "build", "command"].
  • cwdDir: (string) The directory from which to run the build.command. Defaults to ./frontend.
  • env: (Map) A key/value mapping of environment variables and values to inject into the frontend build.
• stackName: (string) Name of the CloudFormation stack for the frontend. Defaults to <service-name>-<stage>-<region>.
• bucket: (Map)
  • name: (string) Name of the S3 Bucket to upload the distDir to. Defaults to a generated name.
  • indexDocument: (string) Defaults to index.html.
  • errorDocument: (string) Defaults to index.html.
• distribution: (Map)
  • dnsName: (string Required) A DNS name to use for this Cloudfront distribution. This is required and has no default values.
  • altDnsName: (string) Another DNS name to use for this Cloudfront distribution.
  • acmCertificateArn: (string, Required) AWS ACM Certificate Arn that covers the domain names listed in aliases.
  • hostedZoneName: (string) Name of the AWS Route53 Hosted Zone to create the Route53 records. Defaults to the value of dnsName.
  • mimeTypes: (Map) A key/value mapping of file extensions and mime types to override. For example:

  ...
    distribution:
      mimeTypes:
        html: text/html # default

• offline: (Map)
  • command: (string[]) Command and options as an array of strings. For example, ["npm", "start"] Defaults to ["echo", "no", "frontend", "offline", "command"].
  • env: (Map) A key/value mapping of environment variables and values to inject into the frontend start command.
  • cwdDir: (string) The directory from which to run the offline.command. Defaults to ./frontend.

Offline Integration

This plugin seamlessly integrates with serverless-offline. Simply Add an offline configuration under custom.serverless-frontend-plugin in your serverless.yml. See offline options above.

Examples

See the test configs on Github for working examples. Just be sure to replace the following section in the serverless.yml:

# Replace this
plugins:
  - ../../../index.js

# With this
plugins:
- serverless-frontend-plugin