# 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.

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"
  }
}
```

- A [Hangar account](https://tryhangar.io/register).

## 1. Create 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`.

## 2. Set environment variables

Add your variables in the service's **Variables** tab.

> [!IMPORTANT]
> Next.js inlines every `NEXT_PUBLIC_` variable into the browser bundle **at build time**. Set those as build arguments as well, so they exist while the image is built. Server-only variables are read at runtime and need nothing special.

## 3. Deploy

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

## 4. Add 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](https://tryhangar.io/docs/domains).

## 5. Push 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:

```js
// 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](https://tryhangar.io/guides/deploy-dockerfile) 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](https://tryhangar.io/docs/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.
