pr-view
v0.1.35
Published
Preview deployments for your pull requests
Downloads
38
Maintainers
Readme
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:
- 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)
- (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
pr-view
uses theserverless
framework to deploy your entire web app to AWS.- It also creates an S3 bucket,
pr-view-deployments
, and DynamoDB table,PrView
. These is used to store metadata relating to managing.serverless
deployments. - For each deployment, it will try to reuse an existing bucket/CloudFront distribution to prevent creating too many new ones.
- 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