next-deploy v1.2.4

Next Deploy

Effortless deployment to AWS and GitHub Pages for Next.js apps 🚀

Table of Contents

• Getting Started
• Features
• Background
• CLI
  • Distributed Deployments
• Environment
  • AWS
  • GitHub
• Configuration Options
  • Base Options
  • AWS Options
  • GitHub Options
• Advanced Usage
  • Redirecting Domains
  • Deployment State
  • CI/CD
• Examples

Getting Started

Make sure your environment is configured to deploy.

• yarn add --dev next-deploy
• yarn next-deploy

Or as a one-liner:

• npx next-deploy

You can safely add the .next-deploy and .next-deploy-build directories to your .gitignore.

Features

Next Deploy strives to support the latest

• ✔ effortless deployment to AWS and GitHub pages
• ✔ deployments to a custom domain
• ✔ static generation (SSG), server side rendering (SSR)
• ✔ serverless AWS architecture serving your Next.js content globally via CloudFront and Lambda@Edge
• ✔ multi-environment support
• ⚠ getStaticPaths with fallback
• ⚠ preview mode
• ⚠ incremental static regeneration

Background

Next Deploy was created to deploy web applications built using the wonderful Next.js 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 which itself is an orchestrator of various orphaned serverless-components.

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

Distributed Deployments

Note how build and deploy can be run separately through the CLI. This allows for creating build artifacts that could be deployed at a later time. You may want to publish such build artifacts to your private artifactory for later retrieval (can be useful for rollbacks) and/or analysis. Consider publishing with the following config in your package.json:

"files": [
    ".next/!(cache)", // not needed for deployment and is very large in size
    ".next-deploy",
    ".next-deploy-build",
    "next-deploy.config.js"
  ]

Environment

AWS

To deploy to AWS you will need to set your credentials in your environment:

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:

[
  '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',
  's3:HeadBucket',
  's3:ListBucket',
  's3:PutAccelerateConfiguration',
  's3:PutBucketPolicy',
  's3:PutObject',
];

GitHub

No specific environment configuration is necessary. By default, your app will be built and exported to the gh-pages branch.

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:

Build

Stage

AWS Options

Github Options

PublicDirectoryCache

CloudFront

Forward

ViewerCertificate

LambdaAtEdge

Advanced Usage

Redirecting Domains

For AWS deployments, when using the domainType option with either apex or domain values, the automatic redirection from the unsupported domain type will not automatically work, but there are manual one time steps you outlined here. In summary, you will have to create a new S3 bucket and set it up with static website hosting to redirect requests to your supported subdomain type (ex. "www.example.com" or "example.com"). To be able to support HTTPS redirects, you'll need to set up a CloudFront distribution with the S3 redirect bucket as the origin. Finally, you'll need to create an "A" record in Route 53 with your newly created CloudFront distribution as the alias target.

Deployment State

For AWS deployments, Next Deploy must know the state of your previous deployment, otherwise it will start spinning up new instances. You may find the local state files in your .next-deploy directory.

When working on a team or trying to implement CI/CD it is advisable to persist the deployment state for each stage using the stage AWS option. Alternatively, one may backup and restore the deployment state by using the onPreDeploy and onPostDeploy callbacks.

CI/CD

Implement CI/CD in your workflow with Next Deploy by substituting environment variables into your next-deploy.config.js.

Consider an advanced configuration example:

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],
  stage: {
    name: process.env.ENVIRONMENT,
    versioned: true,
    bucketName: 'next-environments',
  },
  cloudfront: {
    defaults: {
      'lambda@edge': {
        'viewer-request': process.env.MY_AUTH_LAMBDA_ARN,
      },
    },
  },
  debug: true,
};

The most important configuration option in the example above is stage. It will allow for the deployment state to be persisted in S3 and it will be synced with the locale state at the start of every build.

While implementing CI/CD in your project, consider following the latest Next.js guidelines for storing and loading the environment variables in .env* files.

Examples

Check out the two examples for AWS and GitHub in the examples folder to get a sense of what the implementation will entail and how it will run when deployed.