Skip to content
← Blog

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.

floo team

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:

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:

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:

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

[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. For the general version of this post, see how to deploy an app built with Claude Code.

Frequently asked questions

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.

Get your app live.

read https://getfloo.com/agents.md and set me up on floo

Get an API key
Usage-based pricing. See plans →