# How to deploy a Next.js app built with Claude Code

Deploy a Next.js app Claude Code built: standalone output, a Dockerfile that binds 0.0.0.0, NEXT_PUBLIC_ variables passed at build time, and a floo.app.toml with Postgres and sign-in. The three fixes that stop most first deploys from failing.

Canonical URL: https://getfloo.com/blog/how-to-deploy-a-nextjs-app-built-with-claude-code

## TL;DR

**To deploy a Next.js app built with Claude Code, paste `Read https://getfloo.com/docs/introduction.md and deploy this app to floo.` into Claude Code. It adds `output: "standalone"`, a multi-stage Dockerfile, and `floo.app.toml`, then runs `floo deploy`. Three details decide whether the first deploy works: `HOSTNAME=0.0.0.0`, `NEXT_PUBLIC_` values at build time, and committing before you deploy.**

- Standalone output makes a small image that starts fast.
- Postgres and sign-in are a few lines of `floo.app.toml`.
- Every push to main deploys to the dev URL.

Next.js is what Claude Code reaches for most often when you ask for a web app. It runs well on floo, and the failures that do happen on a first deploy are nearly always the same three.

## 1. Ask Claude Code to deploy it

In the project folder:

```text
Read https://getfloo.com/docs/introduction.md and deploy this app to floo.
```

Claude Code installs the CLI, writes the files below, commits, and runs `floo deploy`. You approve one sign-in in the browser. It waits until the URL is live and fixes the build if it fails.

## 2. The three fixes

**Bind to all interfaces.** Next.js standalone listens on `localhost` unless told otherwise, and floo cannot reach it there. The runtime stage needs:

```dockerfile Dockerfile
ENV HOSTNAME=0.0.0.0
CMD ["node", "server.js"]
```

floo sets `PORT`, and the standalone server reads it, so don't hardcode a port.

**Pass `NEXT_PUBLIC_` values at build time.** They are compiled into the bundle, not read when the server starts. Set the value, add `ARG NEXT_PUBLIC_API_URL` and `ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL` to the build stage, and rebuild:

```bash
floo env set NEXT_PUBLIC_API_URL=https://my-app.getfloo.app --app my-app
floo deploy --rebuild --app my-app
```

Skipping this is the classic "it deployed but the page is broken" bug. Calls to your own API can use relative paths like `/api/orders` and skip it entirely.

**Commit before you deploy.** floo builds from the commit in your GitHub repository, not the files on your machine. A change that only exists locally, such as `output: "standalone"` in `next.config.js`, is not in the build, and the Dockerfile's `COPY --from=build /app/.next/standalone` step fails. Claude Code commits for you; if you edit by hand, commit and push first.

## 3. Add what the app needs

```toml floo.app.toml
[app]
name = "my-app"
access_mode = "accounts"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
dev_command = "npm run dev"

[managed.default]
type = "postgres"
```

- **`access_mode = "accounts"`** makes it invite-only. Route handlers and server components read the person from `X-Floo-User-Email` in the request headers.
- **`[managed.default]`** gives the app Postgres and a `DATABASE_URL`. Dev and prod have separate databases.
- **`dev_command`** is what `floo dev` runs on your machine, with the dev database's credentials.

If Claude Code uses Prisma or Drizzle migrations, add `migrate_command` under `[services.web]`. It runs with the new image before traffic moves, and a failed migration stops the deploy.

## 4. Keep shipping

Every push to main deploys to the dev URL. `floo logs --app my-app` shows what the server printed, and `floo deploys --app my-app` lists versions you can roll back to.

The full guide, with uploads and custom domains, is [Build a Next.js app on floo](https://getfloo.com/docs/build/nextjs). For the general version of this post, see [how to deploy an app built with Claude Code](https://getfloo.com/blog/how-to-deploy-an-app-built-with-claude-code).

## FAQ

### How do I deploy a Next.js app that Claude Code built?

In the project folder, ask Claude Code to read https://getfloo.com/docs/introduction.md and deploy the app to floo. It adds standalone output, a Dockerfile, and floo.app.toml, then runs floo deploy and gives you the URL. Every push after that deploys again.

### Why does my deployed Next.js app show undefined for NEXT_PUBLIC_ variables?

NEXT_PUBLIC_ values are baked into the JavaScript bundle at build time. Set them with floo env set, pass them through the Dockerfile's build stage with ARG and ENV, then rebuild with floo deploy --rebuild. For calls to your own API, relative paths like /api/... avoid the problem.

### Why does my Next.js container start but never answer?

Next.js standalone listens on localhost by default. Set HOSTNAME=0.0.0.0 in the runtime stage of the Dockerfile so floo can reach it, and let the server read PORT from the environment instead of hardcoding one.
