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.

Deploy to Koyeb (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.
  • 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).

This example application should run on any modern version of Node.js. If your application requires a specific Node.js version, add or set the engines section in your package.json file. Consult the build with Node.js page to learn more.

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 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:

Remember to replace the values of <YOUR_GITHUB_USERNAME> and <YOUR_REPOSITORY_NAME> with your own information.

git add .
git commit -m "Initial commit"
git push -u origin main

Deploy to Koyeb using git-driven deployment

To deploy the Next.js app on Koyeb, using the control panel (opens in a new tab) follow the steps below:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Choose the GitHub repository and branch containing your application code. Alternatively, you can enter our public Next.js example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page:
  4. Name the App and Service, for example example-nextjs.
  5. Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

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:


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
COPY package.json package-lock.json ./
RUN npm ci
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
FROM base AS runner
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
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.