Deploy a Next.js App

Next.js (opens in a new tab) is a React-based web framework that lets you quickly build high-performance applications and sites using both client- and server-side rendering. Boasting an active development cycle and a host of large users like Walmart, Apple, and Netflix, Next.js is a great choice for Node developers looking to build stable, modern web experiences.

This guide explains how to deploy a Next.js application to Koyeb using:

1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
2. Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Next.js application from this guide using the Deploy to Koyeb button below.

(opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Next.js app

Get started by creating a minimalistic Next.js application that we will deploy to Koyeb. You will need Node.js (opens in a new tab) installed on your machine.

To generate a new Next.js application, run the npx create-next-app@latest command. This will ask you some questions about your project requirements, create the appropriate directory structure, and install the necessary dependencies.

For this example, we are making the following selections:

• using the name example-nextjs for our application
• using TypeScript
• including a src directory
• using the app router
• declining to customize the default import alias

The answers to the other questions depend on what features and other projects you want to use when building your application. We declined these during this demo to keep the example relatively minimal:

$ npx create-next-app@latest
✔ What is your project named? … example-nextjs
✔ Would you like to use TypeScript with this project? … No / Yes
✔ Would you like to use ESLint with this project? … No / Yes
✔ Would you like to use Tailwind CSS with this project? … No / Yes
✔ Would you like to use `src/` directory with this project? … No / Yes
✔ Use App Router (recommended)? … No / Yes
✔ Would you like to customize the default import alias? … No / Yes
Creating a new Next.js app in /home/demouser/repos/example-nextjs.
 
Using npm.
 
Initializing project with template: app
 
 
Installing dependencies:
- react
- react-dom
- next
- typescript
- @types/react
- @types/node
- @types/react-dom
 
 
added 28 packages, and audited 29 packages in 6s
 
4 packages are looking for funding
  run `npm fund` for details
 
found 0 vulnerabilities
Initialized a git repository.
 
Success! Created example-nextjs at /home/demouser/repos/example-nextjs

Next, move into the generated project directory to view the project's files:

cd example-nextjs

Your directory structure should now include the following files and directories:

• .git/: An initialized Git directory to hold internal version control information.
• .gitignore: To ignore files that should not be committed to the repository. Pre-filled with JavaScript and TypeScript ignore patterns.
• next.config.js: For advanced project configuration. Used during the Next.js server and build phase.
• next-env.d.ts: Ensures Next.js types are recognized by the TypeScript compiler.
• node_modules/: To store project dependencies.
• package.json: Basic Node.js configuration, metadata, and dependency file.
• package-lock.json: Lock file to record exact versions of dependencies installed for the project.
• public/: To store static files.
• README.md: An initialized README file with basic information about using Next.js projects.
• src/app/: Contains React components that configure application routes (opens in a new tab).
• tsconfig.json: TypeScript compiler options and root files specification.

The files and directories you see might be different depending on the options you selected when starting your Next.js project. If any are unfamiliar, you can find out by checking out the Next.js documentation (opens in a new tab).

Run the Next.js app locally

Next, launch the application locally to make sure everything is running as expected.

To start up the included development server, type:

npm run dev

If you navigate to http://127.0.0.1:3000 in your browser, you will see a standard Next.js landing page, indicating that your new project is running successfully in the development server.

Press CTRL-C to stop the development server after verifying.

Push the project to GitHub

Next.js automatically creates a Git repository when you start a new project. Now that you've verified that the project runs locally, commit the changes to the repository and push them up to GitHub.

Run the following commands to commit and push changes to the repository:

git add .
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Deploy to Koyeb using git-driven deployment

Deploy to Koyeb using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the Next.js application, modify the next.config.js configuration file to add an output option (opens in a new tab). Next.js will statically analyze the project files and output the minimum files needed to run the project in production to the .next/standalone directory the project is built.

To configure this, open the next.config.js and add the following line:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}
 
module.exports = nextConfig

Next, add a file called .dockerignore to the project's root directory. Paste the following contents to limit the files copied to the Docker image:

Dockerfile
.dockerignore
node_modules
npm-debug.log
README.md
.next
.git

Finally, create a Dockerfile in your project root directory and copy the content below:

FROM node:18-alpine AS base
 
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
 
FROM base AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
ENV PORT 3000
CMD ["node", "server.js"]

The Dockerfile above provides the minimum requirements to run the Next.js application. You can easily extend it depending on your needs.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.