pr-view

pr-view [Work in Progress]

:warning: Note: this is a work in progress and the interface may change significantly before being stable. Please use at your own risk.

pr-view allows you to create preview deployments for your web app pull requests (PR). Share your web app (including all static assets) with others before merging your PR.

Your PR will be deployed as a Serverless Framework app hosted in AWS, using Serverless Next.js component, which uses Lambda@Edge, S3, CloudFront. In addition, DynamoDB is also lightly used for managing pr-view metadata. This project was inspired by preview deployments such as those in ZEIT or Netlify.

Currently pr-view requires:

• Your own CI/CD provider such as GitHub Actions
• GitHub Actions to write PR comment and also trigger cleanup on PR being closed
• Node.js/npm environment
• Next.js framework (more frameworks may be added in the future)
• AWS account
• Requires: aws cli (looking into how to replace it with the AWS SDK for JavaScript)

Note that the AWS services used do incur a small cost (mainly transactional/transfer costs, but S3 also has a small storage cost), but it should be minimal given that PR preview deployments should not be frequently accessed, unless you are doing some sort of performance/load testing. You can also take advantage of the 12 month free tier for S3/DynamoDB/CloudFront.

Installation

Ensure you have installed Serverless globally by running:

yarn global add serverless

Note: I have tried running a locally serverless binary within pr-view but somehow on GitHub actions it isn't reliably running all the time. Added an issue to address this.

Locally

Install pr-view by running the following command:

npm:

npm install pr-view --save-dev

yarn:

yarn add -D pr-view

Globally

npm:

npm install -g pr-view

yarn:

yarn global add pr-view

Usage

For a more detailed example, see: examples/circleci-nextjs-app

Configure

Create pr-view.json file at the root of your Next.js app:

{
  "appName": "pr-view-nextjs-app",
  "memorySize": 512,
  "framework": "next.js"
}

No domain is required as builds are automatically deployed to CloudFront.

Deploy in CI/CD build

Add the following command in your CI/CD build as a step in your PR builds:

pr-view deploy (prefix yarn run or npm run for local execution)

If a domain is provided in pr-view.json, it sets {branchName}.{appName}-pr-view.{domainName} as the URL. After the deployment is complete, it will append a comment on your PR.

Recommended: for the fastest preview deployments, create a separate build job for pr-view that runs in parallel to your normal PR build that runs tests. This separate build does not need to build the Next.js app as serverless-next.js should do it for you, and you also may choose not to run tests.

Clean stale deployments

To delete deployments once PRs are merged/closed, you can do it one of two ways:

1. Webhook to trigger a build when a PR is merged/closed.

Run the following command: pr-view cleanup (prefix yarn run or npm run for local execution)

This will mark the pr-view deployment associated with this PR as free so that its CloudFront/Lambda/Bucket can be reused by another PR.

TODO: app contents will be emptied to save on S3 storage costs (though this should be minimal, as apps are usually ~1-2 MB)

1. (TODO) Use scheduled workflow to clean up all stale PR preview deployments. In the future, this will periodically mark pr-view deployments as free if the corresponding PRs are closed. This is a fallback for (a) in case your CI/CD provider does not allow triggering on pull requests closing or (b) in case the cleanup workflow fails.

How it works

1. pr-view uses the serverless framework to deploy your entire web app to AWS.
2. It also creates an S3 bucket, pr-view-deployments, and DynamoDB table, PrView. These is used to store metadata relating to managing .serverless deployments.
3. For each deployment, it will try to reuse an existing bucket/CloudFront distribution to prevent creating too many new ones.
4. You can configure it to run as part of your PR open/merge builds.

Contributing

You're welcome to contribute a pull request.

License

pr-view is licensed under the MIT License.

Miscellaneous

Special thanks to the authors of the following projects:

• serverless
• serverless-next.js