Deploy a Next.js app

Deploy a Next.js app on Hangar from a Git repository, with server rendering, a custom domain, HTTPS and a deploy on every push.

Updated

Markdown

Skip the setup

Deploy a working starter of this guide, on its own URL, in one click.

Deploy on Hangar

Next.js runs on Hangar as a Node.js server in a container. That means the whole framework works, not only static export: server components, route handlers, server actions, middleware and ISR.

Before you start#

  • A Next.js app in a Git repository, with build and start scripts in package.json:
JSON
{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

1Create the service#

Create a project, add a service and pick your repository and branch. Choose the region closest to your users.

Leave the builder on Automatic. It detects Next.js, uses the package manager your lockfile points to (npm, pnpm, Yarn or Bun), runs build and starts the app with start.

2Set environment variables#

Add your variables in the service's Variables tab.

3Deploy#

Start the deploy and follow the build log. The first build installs every dependency; later builds reuse the cache.

4Add a domain#

In Settings → Networking, generate a domain or add your own, set the container port to 3000 and turn HTTPS on. The certificate is issued and renewed for you. Details in Domains and HTTPS.

5Push to deploy#

Every push to the connected branch now builds and deploys. If a release misbehaves, roll back to the previous deploy from the service's deployments.

Smaller images with standalone output#

Optional, but worth it for larger apps. Standalone output copies only the files the server needs:

JavaScript
// next.config.js
module.exports = {
  output: "standalone",
};

With standalone output, build with a Dockerfile so you control what is copied into the final image. The Dockerfile guide shows how to deploy one.

Adding a database#

Create a PostgreSQL database in the same project and region, copy its internal connection URL and save it as DATABASE_URL. If you use Prisma or Drizzle, run migrations before the server. The simplest way is a script in package.json, which npm runs through a shell:

JSON
"start": "prisma migrate deploy && next start"

See Databases.

Troubleshooting#

  • The domain returns 502: the container port is not 3000, or a custom server listens on 127.0.0.1. Listen on 0.0.0.0.
  • A NEXT_PUBLIC_ value is undefined in the browser: it was not available during the build. Add it as a build argument and redeploy.
  • The build runs out of memory: raise the service's memory limit, or build with a Dockerfile and standalone output.

Frequently asked questions

Does Hangar run Next.js server features, or only static export?
Hangar runs your app as a long-lived Node.js server in a container, so server components, route handlers, server actions, middleware and incremental static regeneration all work as they do with next start.
Do I need a Dockerfile to deploy Next.js on Hangar?
No. The automatic builder detects Next.js, installs dependencies with your package manager, runs the build and starts the server. A Dockerfile is optional, for when you want full control of the image.
Which port does a Next.js app use on Hangar?
next start listens on port 3000 unless you change it, so set the domain's container port to 3000.