# Next Deploy
Effortless deployment for Next.js apps 🚀
## Table of Contents
- [Getting Started](#Getting-Started)
- [Features](#Features)
- [Background](#Background)
- [CLI](#CLI)
- [Environment](#Environment)
- [GitHub](#GitHub)
- [AWS](#AWS)
- [Configuration Options](#Configuration-Options)
- [Base Options](#Base-Options)
- [GitHub Options](#GitHub-Options)
- [AWS Options](#AWS-Options)
- [Advanced Usage](#Advanced-Usage)
- [Persisting Deployment State](#Persisting-State)
- [CI/CD](#CICD)
## Getting Started
Make sure your environment is [configured to deploy](#Configuration).
Run your deployment with a one-liner:
- `npx next-deploy`
Optionally you can also add and run `next deploy` from your Next.js app:
- `yarn add --dev next-deploy`
- `yarn next-deploy`
## Features
TODO
## Background
Next Deploy was created to deploy web applications built using the wonderful [Next.js](https://nextjs.org/) framework. It allows teams to easily integrate with the supported engines (AWS, GitHub Pages) and keep the entirety of their code in source control. From frontend, to backend, to the deployment logic.
Next Deploy started as a fork of [serverless-next.js](https://github.com/serverless-nextjs/serverless-next.js) which itself is an orchestrator of various orphaned [serverless-components](https://github.com/serverless-components/). Next Deploy was created out of a need for a better, strongly typed codebase and an ability to provide more advanced functionality without the [influence of corporate backers](https://opencollective.com/goserverless#section-contributions).
## CLI
Next Deploy comes with a `next-deploy [argument]` CLI that you can run with `npx next-deploy` or `yarn next-deploy`.
There are currently 5 supported arguments:
- **Default** (default): Runs **Build** followed by **Deploy**.
- **Init**: Creates the base next-deploy.config.js configuration for your project.
- **Build**: Build the application for deployment.
- **Deploy**: Deploy the built application.
- **Remove**: Remove the deployed resources. Note that some resources (such as lambda@edge lambdas need to be cleaned up manually due to a timing constraint).
## Environment
### GitHub
No specific environment configuration is necessary. By default, your app will be built and exported to the `gh-pages` branch.
### AWS
To deploy to AWS you will need to set your credentials in your environment:
```bash
AWS_ACCESS_KEY_ID=******
AWS_SECRET_ACCESS_KEY=******
```
If your account is restricted, ensure that you have enough permissions to deploy.
You will need the following permissions:
Click to view
```javascript
[
'acm:DescribeCertificate', // only for custom domains
'acm:ListCertificates', // only for custom domains
'acm:RequestCertificate', // only for custom domains
'cloudfront:CreateCloudFrontOriginAccessIdentity',
'cloudfront:CreateDistribution',
'cloudfront:CreateInvalidation',
'cloudfront:GetDistribution',
'cloudfront:GetDistributionConfig',
'cloudfront:ListCloudFrontOriginAccessIdentities',
'cloudfront:ListDistributions',
'cloudfront:ListDistributionsByLambdaFunction',
'cloudfront:ListDistributionsByWebACLId',
'cloudfront:ListFieldLevelEncryptionConfigs',
'cloudfront:ListFieldLevelEncryptionProfiles',
'cloudfront:ListInvalidations',
'cloudfront:ListPublicKeys',
'cloudfront:ListStreamingDistributions',
'cloudfront:UpdateDistribution',
'iam:AttachRolePolicy',
'iam:CreateRole',
'iam:CreateServiceLinkedRole',
'iam:GetRole',
'iam:PassRole',
'lambda:CreateFunction',
'lambda:EnableReplication',
'lambda:DeleteFunction', // only for custom domains
'lambda:GetFunction',
'lambda:GetFunctionConfiguration',
'lambda:PublishVersion',
'lambda:UpdateFunctionCode',
'lambda:UpdateFunctionConfiguration',
'route53:ChangeResourceRecordSets', // only for custom domains
'route53:ListHostedZonesByName',
'route53:ListResourceRecordSets', // only for custom domains
's3:CreateBucket',
's3:GetAccelerateConfiguration',
's3:GetObject', // only if persisting state to S3 for CI/CD
's3:HeadBucket',
's3:ListBucket',
's3:PutAccelerateConfiguration',
's3:PutBucketPolicy',
's3:PutObject',
];
```
## Configuration Options
The next-deploy config varies by the provider (engine) that you're deploying to. All configuration options are optional and come with sensible defaults.
The deployment configuration is to be provided through `next-deploy.config.js`, which will be automatically created for you the first time you run `next-deploy` or `next-deploy init`.
### Base Options
All engines support the basic options:
| Name | Type | Default | Description |
| ------------- | --------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| engine | `"aws"\|"github"` | `aws` | The platform to deploy to. |
| debug | `boolean` | `false` | Print helpful messages to |
| onPreDeploy | `() => Promise` | `null` | A callback that gets called before the deployment. |
| onPostDeploy | `() => Promise` | `null` | A callback that gets called after the deployment successfully finishes. |
| onShutdown | `() => Promise` | `null` | A callback that gets called after the deployment is shutdown by a INT/QUIT/TERM signal like from ctrl+c. |
| build | [`Build`](#Build) | `{}` | Build related options. |
| nextConfigDir | `string` | `./` | The directory holding the `next.config.js`. |
| domain | `string\|string[]` | `null` | The domain to deploy to . |
#### Build
| Name | Type | Default | Description |
| ---- | ---------- | ------------------------ | ---------------------------------------------------- |
| cmd | `string` | `node_modules/.bin/next` | The build command. |
| args | `string[]` | `['build']` | A list of arguments to provide to the build command. |
| cwd | `string` | `./` | The current working directory. |
### Github Options
| Name | Type | Default | Description |
| ------- | -------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| publish | [`Publish`](https://github.com/tschaub/gh-pages#options) | `{message: "Next Deployment Update", dotfiles: true}` | The [git-hub page options](https://github.com/tschaub/gh-pages#options) to publish with. |
### AWS Options
| Name | Type | Default | Description |
| -------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucketName | `string` | `*auto generated*` | Custom bucket name where static assets are stored. |
| bucketRegion | `string` | `us-east-1` | Region where you want to host your S3 bucket. |
| publicDirectoryCache | `boolean\|`[`PublicDirectoryCache`](#PublicDirectoryCache) | `true` | Customize the public/static directory asset caching policy. Assigning an object lets you customize the caching policy and the types of files being cached. Assigning false disables caching. |
| memory | `number` | `512` | The amount of memory that a lambda has access to. Increasing the lambda's memory also increases its CPU allocation. The value must be a multiple of 64 MB. |
| timeout | `number` | `10` | The amount of time that the lambda allows a function to run before stopping it. The maximum allowed value is 900 seconds. |
| name | `string` | `*auto generated*` | The name of the lambda function. |
| runtime | `string` | `nodejs12.x` | The identifier of the lambda's runtime. |
| description | `string` | `"*lambda type* handler for the Next CloudFront distribution."` | A description of the lambda. |
| policy | `string` | `arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole` | The arn policy of the lambda. |
| domainType | `"www"\|"apex"\|"both"` | `both` | Can be one of: "**apex**" - apex domain only, don't create a www subdomain. "**www**" - www domain only, don't create an apex subdomain. "**both**" - create both www and apex domains when either one is provided. |
| cloudfront | [`CloudFront`](#CloudFront) | `{}` | Additional cloudfront options. |
#### PublicDirectoryCache
| Name | Type | Default | Description |
| ----- | -------- | --------------------------------------------------------- | ---------------------------------------- |
| test | `string` | `/\.(gif\|jpe?g\|jp2\|tiff\|png\|webp\|bmp\|svg\|ico)$/i` | The test to apply the caching behaviour. |
| value | `string` | `public, max-age=31536000, must-revalidate` | The caching behavior. |
#### CloudFront
| Name | Type | Default | Description |
| ---------------------- | ----------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ttl | `number` | `0` | The amount of time that you want objects to stay in CloudFront's cache before it forwards another request to determine whether the object has been updated. |
| smoothStreaming | `boolean` | `false` | Indicates whether you want to distribute media files in the Microsoft Smooth Streaming format. |
| viewerProtocolPolicy | `string` | `redirect-to-https` | The policy for viewers to access the content. |
| fieldLevelEncryptionId | `string` | `""` | The value of the ID for the field-level encryption configuration that you want to use. |
| forward | [`Forward`](#Forward) | `{}` | Determines the forwarding configuration |
| viewerCertificate | [`ViewerCertificate`](#ViewerCertificate) | `{}` | Determines the SSL/TLS configuration for communicating with viewers. |
| "lambda@edge" | [`LambdaAtEdge`](#LambdaAtEdge) | `{}` | Additional lambda@edge functions. |
#### Forward
| Name | Type | Default | Description |
| -------------------- | ------------------ | ------- | ------------------------------------------------------------------------ |
| cookies | `string\|string[]` | `all` | Indicates which cookies should be forwarded. |
| queryString | `boolean` | `true` | Indicates whether the query string should be forwarded. |
| headers | `string[]` | `[]` | Headers to forward (whitelisted headers). |
| queryStringCacheKeys | `string[]` | `[]` | Details of the query string parameters that you want to use for caching. |
#### ViewerCertificate
| Name | Type | Default | Description |
| ---------------------- | -------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ACMCertificateArn | `string` | `null` | If the SSL/TLS certificate is stored in ACM, provide the ARN of the ACM certificate. CloudFront only supports ACM certificates in the us-east-1. |
| SSLSupportMethod | `string` | `sni-only` | Specifies which viewers the distribution accepts HTTPS connections from. **sni-only** – The distribution accepts HTTPS connections only from viewers that support server SNI (all modern browsers). **vip** – The distribution accepts HTTPS connections from **all** (not recommended and results in additional monthly charges). |
| minimumProtocolVersion | `string` | `TLSv1.2_2018` | The security policy that you want to use for HTTPS connections with viewers. |
#### LambdaAtEdge
| Name | Type | Default | Description |
| ------------------ | ------------------------------------------ | ------- | ----------------------------------------------------------------------- |
| _cloudfront event_ | `string\|{arn:string,includeBody:boolean}` | `null` | The customization for a new CloudFront event handler (lambda function). |
## Advanced Usage
### Persisting State
TODO
### CI/CD
Implement [CI/CD](#https://en.wikipedia.org/wiki/CI/CD) in your workflow with Next Deploy by substituting environment variables into your `next-deploy.config.js`.
As an example:
```javascript
module.exports = {
bucketName: process.env.MY_APP_BUCKET_NAME,
description: process.env.MY_APP_LAMBDA_DESCRIPTION,
name: {
requestLambda: process.env.MY_APP_REQUEST_LAMBDA_NAME,
},
domain: [process.env.MY_APP_SUBDOMAIN, process.env.MY_APP_DOMAIN],
debug: true,
};
```
TODO