serverless-amplify-plugin

A Serverless Framework plugin that enables you to easily host static websites with AWS Amplify Console including Continuous Deployment in as few as 3 lines of YAML.

Developed and maintained by Wizeline. Looking for a partner to help build your software or expand your existing team with veteran engineers, project managers, technical writers and more? Reach out to us at Wizeline.

Usage

npm i -D @wizeline/serverless-amplify-plugin

# serverless.yaml
plugins:
  - serverless-amplify-plugin

custom:
  amplify:
    repository: https://github.com/USER/REPO # required
    accessTokenSecretName: AmplifyGithub # optional
    accessTokenSecretKey: accessToken # optional
    branch: master # optional
    domainName: example.com # optional;
    buildSpec: |- # optional
      version: 0.1
      frontend:
        ...
    buildSpecValues: # optional
      artifactBaseDirectory: 'dist' # optional
      artifactFiles: ['**/*'] # optional

🔒 Securing your GitHub Personal Access Token Secret

It's important not to paste your GitHub Personal Access Token directly into the accessToken property. At a minimum, you should use ${{env:GITHUB_PERSONAL_ACCESS_TOKEN}} along with the serverless-dotenv-plugin, however, this will still be visible in the CloudFormation template and logs.

The recommended way is to store your secret in AWS Secrets Manager. You can do this via the AWS Console or by running this command (ensure your profile and region are correct):

aws secretsmanager create-secret --name AmplifyGithub --secret-string '{"accessToken":"YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"}' --profile YOUR_PROFILE --region YOUR_REGION

Options

repository (required)

The GitHub repository URL (https://github.com/USER/REPO) of the project for which you want to set up Continuous Deployment and hosting.

accessTokenSecretName (optional)

Shorthand equivalent of accessToken: '{{resolve:secretsmanager:AmplifyGithub:SecretString:personalAccessToken}}' where:

accessTokenSecretName: AmplifyGithub
accessTokenSecretKey: personalAccessToken

Default: AmplifyGithub

accessTokenSecretKey (optional)

Default: accessToken

🔒 accessToken (required*)

A GitHub Personal Access Token with repo permissions. Amplify Console sets up a GitHub Webhook so that it can be notified of new commits to build and deploy any changes.

🔒 This is a secret! It's recommended to store this in AWS Secrets Manager.

branch (optional)

Amplify Console is notified of changes to this branch.

Default: master

domainName (optional)

When specified, Amplify Console sets up a custom domain name for your application. You will need to perform additional steps to verify the domain with your DNS provider and approve the SSL Certificate.

Default: None. When deployed, your website is accessible via a subdomain https://{branchName}.{appId}.amplifyapp.com.

buildSpec (optional)

Amplify Console executes a build according to these instructions. See Configuring Build Settings for more information.

Default: A standard build spec that runs npm ci and npm run build and expects build artifacts to be stored in dist/:

version: 0.1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

buildSpecValues (optional)

Specify values in the buildSpec. Useful so that you don't need to provide your own custom buildSpec if you just need to override some values that are commonly different between projects.

artifactBaseDirectory (optional)

Sets frontend.artifacts.baseDirectory in buildSpec.

Default: dist

artifactFiles (optional)

Sets frontend.artifacts.baseDirectory in buildSpec.

Default: ['**/*']

Limitations and future considerations

This plugin is currently only written with a basic single branch setup in mind. In the future we'd like to add support for all of Amplify Console's features including:

1. Multiple branches
2. Multiple domains
3. PR Previews
4. Environment Variables
5. Email Notifications
6. Access Control
7. Rewrites and redirects