pr-view/README.md

Preview deployments for your pull requests

# 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)

2. (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`