Deploy a Next.js App

Next.js 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. 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.

You can consult the repository on GitHub 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 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.
• 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 my by checking out the Next.js documentation.

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.

Deploy the Next.js app on Koyeb using git-driven deployment

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 remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Via the Koyeb control panel

To deploy the Next.js app on Koyeb, using the control panel follow the steps below:

1. Click Create App in the Koyeb control panel.
2. Select GitHub as the deployment option.
3. Choose the GitHub repository and branch containing your application code.
4. Name your service, for example nextjs-service.
5. Name the App, for example example-nextjs.
6. 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 .koyeb.app.

Via Koyeb CLI

To deploy the Next.js app on Koyeb using the Koyeb CLI, run the following command in your terminal:

koyeb app init example-nextjs \
  --git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> \
  --git-branch main \
  --ports 3000:http \
  --routes /:3000 \
  --env PORT=3000

Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Access deployment logs

To track the app deployment and visualize build logs, execute the following command:

koyeb service logs example-nextjs/example-nextjs -t build

Access your app

Once the deployment of your application has finished, you can retrieve the public domain to access your application by running the following command:

$ koyeb app get example-nextjs
ID      	NAME         	DOMAINS                          	CREATED AT
55d75993	example-nextjs	["example-nextjs-myorg.koyeb.app"]	20 Apr 23 09:55 UTC

Access runtime logs

With your app running, you can track the runtime logs by running the following command:

koyeb service logs example-nextjs/example-nextjs -t runtime

Deploy the Next.js app on 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. 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 Deploy an app from a Docker image documentation.