pr-view

pr-view [Work in Progress]

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 deploy preview deployments for your web app pull requests (PR). Share your web app (including all static assets) with others before checking in your code.

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 to be added soon)
• AWS account
• Requires: aws cli (will replace it soon with AWS SDK for JavaScript)

Note that Lambda@Edge, S3, and CloudFront do incur a small cost, but it should be minimal given that PR preview deployments should not be frequently accessed.

Installation

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",
  "domain": "example.com"
}

Run 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 faster preview deployments, create a separate build job for pr-view that runs in parallel to your PR build.

Deleting 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. Its bucket contents are also emptied to save storage costs.

1. (TODO) Use scheduled workflow to clean up all stale PR preview deployments.

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, This is used to store metadata relating to managing .serverless deployments.
3. 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