From 26ddf32f53f24dd4a56b10ee2b668aebe17cb6b1 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 5 Jan 2022 15:56:05 -0600 Subject: [PATCH] Update deployment documentation. (#32006) Building off https://github.com/vercel/next.js/pull/31465 for `next export` docs. - Clearly explains the standard output from `next build` - Move Dockerfile snippet to example, instead of embedded directly - Clarify both Vercel and `next start` use the Build API output spec - Less emphasis on recommending Vercel (more neutrality) - Mention Middleware & Edge Functions when discussing Vercel - Add "Going to Production" link at the bottom for related reading --- docs/deployment.md | 156 +++++++++++++++++---------------------------- 1 file changed, 60 insertions(+), 96 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 91d806aa3881a..8c0498ff95cab 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,68 +1,67 @@ --- -description: Deploy your Next.js app to production with Vercel and other hosting options. +description: Learn how to deploy your Next.js app to production, either managed or self-hosted. --- # Deployment -## Vercel (Recommended) +Congratulations, you are ready to deploy your Next.js application to production. This document will show how to deploy either managed or self-hosted using the [Next.js Build API](#nextjs-build-api). -The easiest way to deploy Next.js to production is to use the **[Vercel platform](https://vercel.com)** from the creators of Next.js. [Vercel](https://vercel.com) is a cloud platform for static sites, hybrid apps, and Serverless Functions. +## Next.js Build API -### Getting started +`next build` generates an optimized version of your application for production. This standard output includes: -If you haven’t already done so, push your Next.js app to a Git provider of your choice: [GitHub](https://github.com/), [GitLab](https://gitlab.com/), or [BitBucket](https://bitbucket.org/). Your repository can be private or public. +- HTML files for pages using `getStaticProps` or [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) +- CSS files for global styles or for individually scoped styles +- JavaScript for pre-rendering dynamic content from the Next.js server +- JavaScript for interactivity on the client-side through React -Then, follow these steps: +This output is generated inside the `.next` folder: -1. [Sign up to Vercel](https://vercel.com/signup) (no credit card is required). -2. After signing up, you’ll arrive on the [“Import Project”](https://vercel.com/new) page. Under “From Git Repository”, choose the Git provider you use and set up an integration. (Instructions: [GitHub](https://vercel.com/docs/git/vercel-for-github) / [GitLab](https://vercel.com/docs/git/vercel-for-gitlab) / [BitBucket](https://vercel.com/docs/git/vercel-for-bitbucket)). -3. Once that’s set up, click “Import Project From …” and import your Next.js app. It auto-detects that your app is using Next.js and sets up the build configuration for you. No need to change anything — everything should work fine! -4. After importing, it’ll deploy your Next.js app and provide you with a deployment URL. Click “Visit” to see your app in production. +- `.next/static/chunks/pages` – Each JavaScript file inside this folder relates to the route with the same name. For example, `.next/static/chunks/pages/about.js` would be the JavaScript file loaded when viewing the `/about` route in your application +- `.next/static/media` – Statically imported images from `next/image` are hashed and copied here +- `.next/static/css` – Global CSS files for all pages in your application +- `.next/server/pages` – The HTML and JavaScript entry points prerendered from the server. The `.nft.json` files are created when [Output File Tracing](/docs/advanced-features/output-file-tracing.md) is enabled and contain all the file paths that depend on a given page. +- `.next/server/chunks` – Shared JavaScript chunks used in multiple places throughout your application +- `.next/cache` – Output for the build cache and cached images, responses, and pages from the Next.js server. Using a cache helps decrease build times and improve performance of loading images -Congratulations! You’ve deployed your Next.js app! If you have questions, take a look at the [Vercel documentation](https://vercel.com/docs). +All JavaScript code inside `.next` has been **compiled** and browser bundles have been **minified** to help achieve the best performance and support [all modern browsers](/docs/basic-features/supported-browsers-features.md). -> If you’re using a [custom server](/docs/advanced-features/custom-server.md), we strongly recommend migrating away from it (for example, by using [dynamic routing](/docs/routing/dynamic-routes.md)). If you cannot migrate, consider [other hosting options](#other-hosting-options). +## Managed Next.js with Vercel -### DPS: Develop, Preview, Ship +[Vercel](https://vercel.com/) is a frontend cloud platform from the creators of Next.js. It's the fastest way to deploy your managed Next.js application with zero configuration. -Let’s talk about the workflow we recommend using. [Vercel](https://vercel.com) supports what we call the **DPS** workflow: **D**evelop, **P**review, and **S**hip: +When deploying to Vercel, the platform automatically detects Next.js, runs `next build`, and optimizes the build output for you, including: -- **Develop:** Write code in Next.js. Keep the development server running and take advantage of [React Fast Refresh](https://nextjs.org/blog/next-9-4#fast-refresh). -- **Preview:** Every time you push changes to a branch on GitHub / GitLab / BitBucket, Vercel automatically creates a new deployment with a unique URL. You can view them on GitHub when you open a pull request, or under “Preview Deployments” on your project page on Vercel. [Learn more about it here](https://vercel.com/features/deployment-previews). -- **Ship:** When you’re ready to ship, merge the pull request to your default branch (e.g. `main`). Vercel will automatically create a production deployment. +- Persisting cached assets across deployments if unchanged +- [Immutable deployments](https://vercel.com/features/previews) with a unique URL for every commit +- [Pages](/docs/basic-features/pages.md) are automatically statically optimized, if possible +- Assets (JavaScript, CSS, images, fonts) are compressed and served from a [Global Edge Network](https://vercel.com/features/infrastructure) +- [API Routes](/docs/api-routes/introduction.md) are automatically optimized as isolated [Serverless Functions](https://vercel.com/features/infrastructure) that can scale infinitely +- [Middleware](/docs/middleware.md) are automatically optimized as [Edge Functions](https://vercel.com/features/edge-functions) that have zero cold starts and boot instantly -By using the DPS workflow, in addition to doing _code reviews_, you can do _deployment previews_. Each deployment creates a unique URL that can be shared or used for integration tests. +In addition, Vercel provides features like: -### Optimized for Next.js +- Automatic performance monitoring with [Next.js Analytics](/analytics) +- Automatic HTTPS and SSL certificates +- Automatic CI/CD (through GitHub, GitLab, Bitbucket, etc.) +- Support for [Environment Variables](https://vercel.com/docs/environment-variables) +- Support for [Custom Domains](https://vercel.com/docs/custom-domains) +- Support for [Image Optimization](/docs/basic-features/image-optimization.md) with `next/image` +- Instant global deployments via `git push` -[Vercel](https://vercel.com) is made by the creators of Next.js and has first-class support for Next.js. +You can start using Vercel (for free) through a personal hobby account, or create a team to start the next big thing. Learn more about [Next.js on Vercel](https://vercel.com/solutions/nextjs) or read the [Vercel Documentation](https://vercel.com/docs). -For example, the [hybrid pages](/docs/basic-features/pages.md) approach is fully supported out of the box. +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/hello-world&project-name=hello-world&repository-name=hello-world&utm_source=github.com&utm_medium=referral&utm_campaign=deployment) -- Every page can either use [Static Generation](/docs/basic-features/pages.md#static-generation) or [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering). -- Pages that use [Static Generation](/docs/basic-features/pages.md#static-generation) and assets (JS, CSS, images, fonts, etc) will automatically be served from [Vercel's Edge Network](https://vercel.com/docs/edge-network/overview), which is blazingly fast. -- Pages that use [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering) and [API routes](/docs/api-routes/introduction.md) will automatically become isolated Serverless Functions. This allows page rendering and API requests to scale infinitely. +## Self-Hosting -### Custom Domains, Environment Variables, Automatic HTTPS, and more - -- **Custom Domains:** Once deployed on [Vercel](https://vercel.com), you can assign a custom domain to your Next.js app. Take a look at [our documentation here](https://vercel.com/docs/custom-domains). -- **Environment Variables:** You can also set environment variables on Vercel. Take a look at [our documentation here](https://vercel.com/docs/environment-variables). You can then [use those environment variables](/docs/api-reference/next.config.js/environment-variables.md) in your Next.js app. -- **Automatic HTTPS:** HTTPS is enabled by default (including custom domains) and doesn't require extra configuration. We auto-renew SSL certificates. -- **More:** [Read our documentation](https://vercel.com/docs) to learn more about the Vercel platform. - -## Automatic Updates - -When you deploy your Next.js application, you want to see the latest version without needing to reload. - -Next.js will automatically load the latest version of your application in the background when routing. For client-side navigation, `next/link` will temporarily function as a normal `` tag. - -**Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Then, after either a full page refresh or multiple client-side page transitions, Next.js will show the latest version. - -## Other hosting options +You can self-host Next.js with support for all features using Node.js or Docker. You can also do a Static HTML Export, which [has some limitations](/docs/advanced-features/static-html-export.md). ### Node.js Server -Next.js can be deployed to any hosting provider that supports Node.js. Make sure your `package.json` has the `"build"` and `"start"` scripts: +Next.js can be deployed to any hosting provider that supports Node.js. For example, [AWS EC2](https://aws.amazon.com/ec2/) or a [DigitalOcean Droplet](https://www.digitalocean.com/products/droplets/). + +First, ensure your `package.json` has the `"build"` and `"start"` scripts: ```json { @@ -74,73 +73,38 @@ Next.js can be deployed to any hosting provider that supports Node.js. Make sure } ``` -`next build` builds the production application in the `.next` folder. After building, `next start` starts a Node.js server that supports [hybrid pages](/docs/basic-features/pages.md), serving both statically generated and server-side rendered pages. +Then, run `next build` to build your application. Finally, run `next start` to start the Node.js server. This server supports all features of Next.js. -If you are using [`next/image`](/docs/basic-features/image-optimization.md), consider adding `sharp` for more performant [Image Optimization](/docs/basic-features/image-optimization.md) in your production environment by running `npm install sharp` in your project directory. On Linux platforms, `sharp` may require [additional configuration](https://sharp.pixelplumbing.com/install#linux-memory-allocator) to prevent excessive memory usage. +> If you are using [`next/image`](/docs/basic-features/image-optimization.md), consider adding `sharp` for more performant [Image Optimization](/docs/basic-features/image-optimization.md) in your production environment by running `npm install sharp` in your project directory. On Linux platforms, `sharp` may require [additional configuration](https://sharp.pixelplumbing.com/install#linux-memory-allocator) to prevent excessive memory usage. ### Docker Image -
- Examples - -
- Next.js can be deployed to any hosting provider that supports [Docker](https://www.docker.com/) containers. You can use this approach when deploying to container orchestrators such as [Kubernetes](https://kubernetes.io/) or [HashiCorp Nomad](https://www.nomadproject.io/), or when running inside a single node in any cloud provider. -Here is a multi-stage `Dockerfile` using `node:alpine` that you can use: - -```Dockerfile -# Install dependencies only when needed -FROM node:alpine AS deps -# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed. -RUN apk add --no-cache libc6-compat -WORKDIR /app -COPY package.json yarn.lock ./ -RUN yarn install --frozen-lockfile +1. [Install Docker](https://docs.docker.com/get-docker/) on your machine +1. Clone the [with-docker](https://github.com/vercel/next.js/tree/canary/examples/with-docker) example +1. Build your container: `docker build -t nextjs-docker .` +1. Run your container: `docker run -p 3000:3000 nextjs-docker` -# Rebuild the source code only when needed -FROM node:alpine AS builder -WORKDIR /app -COPY . . -COPY --from=deps /app/node_modules ./node_modules -RUN yarn build && yarn install --production --ignore-scripts --prefer-offline - -# Production image, copy all the files and run next -FROM node:alpine AS runner -WORKDIR /app - -ENV NODE_ENV production - -RUN addgroup -g 1001 -S nodejs -RUN adduser -S nextjs -u 1001 - -# You only need to copy next.config.js if you are NOT using the default configuration -# COPY --from=builder /app/next.config.js ./ -COPY --from=builder /app/public ./public -COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next -COPY --from=builder /app/node_modules ./node_modules -COPY --from=builder /app/package.json ./package.json - -USER nextjs +### Static HTML Export -EXPOSE 3000 +If you’d like to do a static HTML export of your Next.js app, follow the directions on our [Static HTML Export documentation](/docs/advanced-features/static-html-export.md). -ENV PORT 3000 +## Automatic Updates -# Next.js collects completely anonymous telemetry data about general usage. -# Learn more here: https://nextjs.org/telemetry -# Uncomment the following line in case you want to disable telemetry. -# ENV NEXT_TELEMETRY_DISABLED 1 +When you deploy your Next.js application, you want to see the latest version without needing to reload. -CMD ["node_modules/.bin/next", "start"] -``` +Next.js will automatically load the latest version of your application in the background when routing. For client-side navigations, `next/link` will temporarily function as a normal `` tag. -Make sure to place this Dockerfile in the root folder of your project. +**Note:** If a new page (with an old version) has already been prefetched by `next/link`, Next.js will use the old version. Navigating to a page that has _not_ been prefetched (and is not cached at the CDN level) will load the latest version. -You can build your container with `docker build . -t my-next-js-app` and run it with `docker run -p 3000:3000 my-next-js-app`. +## Related -### Static HTML Export +For more information on what to do next, we recommend the following sections: -If you’d like to do a static HTML export of your Next.js app, follow the directions on [our documentation](/docs/advanced-features/static-html-export.md). +
+ + Going to Production: + Ensure the best performance and user experience. + +