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 Next.js web app pull requests. Deploy a preview deployment to share your branch with others in a unique CloudFront URL!

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 Vercel or Netlify.

Currently pr-view requires:

• GitHub Actions to write a PR comment with the deployment URL
• Node.js environment
• Next.js + React
• AWS account with permissions to S3, DynamoDB, Lambda, CloudFront
• 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