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. Wizeline understands that great software is built by great people and teams. If you’d like to partner with Wizeline to build your software or expand your existing team with veteran engineers, project managers, technical writers, reach out to our team.

Usage

Install @wizeline/serverless-amplify-plugin:

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

Create/update your serverless.yaml:

plugins:
  - serverless-amplify-plugin

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

🔒 Create your GitHub Personal Access Token and store it AWS Secrets Manager

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 (optional)

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 your access token in AWS Secrets Manager and reference it in this property with accessToken: '{{resolve:secretsmanager:AmplifyGithub:SecretString:accessToken}}'. Alternatively, specify accessTokenSecretName and accessTokenSecretKey properties.

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.

buildSpecValues.artifactBaseDirectory (optional)

Sets frontend.artifacts.baseDirectory in buildSpec.

Default: dist

buildSpecValues.artifactFiles (optional)

Sets frontend.artifacts.files in buildSpec.

Default: ['**/*']

buildSpecValues.preBuildWorkingDirectory (optional)

Adds a command to the frontend.preBuild.commands list in buildSpec that cds into the path specified. This is especially helpful for Monorepos.

Note: You may also need to prefix buildSpecValues.artifactBaseDirectory with this same path if it builds into that directory.

Default: None - uses project root

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