Build a Next.js app on floo

From a Next.js 14+ App Router project on GitHub to a live app at https://<app>.on.getfloo.com, with managed Postgres, signed-in users, and your own domain. New to floo? Start with the Quickstart.

Before you start

You need:

A Next.js 14+ App Router project (or a fresh npx create-next-app@latest).
The project pushed to a GitHub repository. floo pulls source from GitHub; it does not upload local files.
The floo CLI installed and authenticated (curl -fsSL https://getfloo.com/install.sh | bash then floo auth login).
The floo GitHub App installed on the account that owns the repository. floo apps github connect opens a browser to install it if it is missing.

1. Add a Dockerfile

Configure Next.js for standalone output (much smaller container):

next.config.js

module.exports = {
  output: "standalone",
};

Then a multi-stage Dockerfile that uses it:

Dockerfile

FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

FROM node:22-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV HOSTNAME=0.0.0.0
COPY --from=build /app/public ./public
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
CMD ["node", "server.js"]

floo sets PORT at runtime and the standalone server reads it, so do not hardcode a port. Set HOSTNAME=0.0.0.0: Next.js standalone defaults to localhost, which floo cannot reach.

Add a .dockerignore next to this Dockerfile with at least node_modules, .git, and .env. Without it, COPY . . drags your local node_modules over the clean install from the deps stage and ships your dev dependencies. See Build context.

2. Build-time env vars (`NEXT_PUBLIC_*`)

Any NEXT_PUBLIC_* variable referenced in your code is baked into the JS bundle at build time, not read at runtime. floo passes every env var whose name starts with NEXT_PUBLIC_, VITE_, or REACT_APP_ to the image build as a Docker build arg, and injects it at runtime as well. Two things have to line up. First, set the value as an ordinary env var. No extra flag is needed; the name prefix is what makes it a build arg.

floo env set NEXT_PUBLIC_API_URL=https://my-app-dev.on.getfloo.com --app my-app

Second, thread it through the build stage of the Dockerfile. ARG makes Docker accept the value; the ENV line is what puts it in process.env for next build.

Dockerfile

# In the build stage:
FROM node:22-slim AS build
WORKDIR /app
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

Skipping either step is the most common Next.js failure on floo: the app builds, deploys, and 404s in the browser because the bundle has undefined baked in. The build step records a diagnostic when a build-time var is passed but not threaded into the stage that runs next build. Env vars are per environment (--env dev is the default). A promote rebuilds the image with prod’s values whenever prod has any NEXT_PUBLIC_/VITE_/REACT_APP_ var, and otherwise reuses the dev image with the dev values baked in, so set the var in both environments when the values differ:

floo env set NEXT_PUBLIC_API_URL=https://my-app.on.getfloo.com --app my-app --env prod

For calls to your own app, relative paths (/api/...) avoid the question entirely. See Container contract and Environment variables.

3. Initialize the floo config

floo init my-nextjs-app

For a single-service Next.js app:

floo.app.toml

[app]
name = "my-nextjs-app"

[services.web]
type = "web"
path = "."
port = 3000
ingress = "public"
dev_command = "npm run dev"
migrate_command = "npx prisma migrate deploy"   # optional, if you use Prisma

migrate_command runs as a one-off job with the new image. Release promotion without rebuilding runs it before any application revision changes and blocks promotion if it fails. Fresh deploys run it after deploying the new revisions: with traffic staging enabled, migration precedes cutover; without staging, new code can serve before migration runs. Use expand-then-contract migrations to keep the schema compatible with both old and new code.

4. Connect the repo and deploy

floo preflight
git add . && git commit -m "feat: floo config + Dockerfile"
git push origin main
floo apps github connect owner/my-nextjs-app
floo deploys watch --app my-nextjs-app

When the deploy is green:

floo apps show my-nextjs-app

Your Next.js app is live at https://my-nextjs-app-dev.on.getfloo.com.Every git push origin main ships to dev. floo releases promote --app my-nextjs-app publishes to https://my-nextjs-app.on.getfloo.com.

5. Add a Postgres database

floo.app.toml

[managed.default]
type = "postgres"

floo preflight
git add floo.app.toml && git commit -m "feat: add postgres"
git push origin main

DATABASE_URL is injected into the runtime. With Prisma:

prisma/schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

If you set migrate_command, the next deploy runs npx prisma migrate deploy against the new database. Migration and traffic ordering depend on the deploy path; use expand-then-contract migrations.

6. Add per-user auth

floo manages user authentication for you. Set access_mode = "accounts" in floo.app.toml:

floo.app.toml

[app]
name = "my-nextjs-app"
access_mode = "accounts"

Push and deploy. From the next deploy onward, floo’s gateway sits in front of your app and:

Redirects unauthenticated requests to a hosted login page.
Validates the session cookie on every request.
Injects identity headers into every request that reaches your Next.js app.

Read the headers in a Server Component or Route Handler:

app/dashboard/page.tsx

import { headers } from "next/headers";

export default async function Dashboard() {
  const h = await headers();
  const email = h.get("x-floo-user-email");
  const userId = h.get("x-floo-user-id");
  const name = h.get("x-floo-user-name");

  return (
    <main>
      <h1>Hello {name ?? email}</h1>
      <p>User id: {userId}</p>
    </main>
  );
}

For local development, run floo dev --fixture-user (see section 8) or hit your dev server with curl -H 'X-Floo-User-Email: you@example.com'. For the full reference on access modes and identity headers, see Auth.

7. Add a custom domain

Declare the domain in floo.app.toml:

[domains."app.example.com"]
service = "web"

Commit and push the config, then wait for that commit’s dev deploy to go live. Release it to prod and read the DNS records:

floo releases promote --app my-nextjs-app
floo domains show app.example.com --app my-nextjs-app

Publish the traffic and certificate CNAME records printed by show at your DNS provider, then watch activation:

floo domains watch app.example.com --app my-nextjs-app

See Custom domains for DNS setup and troubleshooting. Next.js reads Host and X-Forwarded-Host from the request, with no extra config needed.

8. Local development with dev credentials

floo dev --app my-nextjs-app

Runs dev_command locally with DATABASE_URL and the other env vars from the app’s dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Prod credentials are never handed to a local session. To also test signed-in flows for this accounts-mode app, add --fixture-user:

floo dev --app my-nextjs-app --fixture-user you@example.com

floo dev then starts a small proxy in front of each service that injects the same X-Floo-User-* headers floo’s gateway adds in production. The output table shows both the raw service URL and the auth-proxied URL. Hit the auth-proxied one for any path that reads identity headers.

Common gotchas

/healthz is reserved. floo’s edge intercepts that exact path. Use /health or /livez.
HOSTNAME=0.0.0.0. Next.js standalone defaults to localhost, which floo cannot reach.
NEXT_PUBLIC_* build args. Set them with floo env set and thread them through the build stage as ARG plus ENV. Otherwise the bundle has undefined baked in.
output: "standalone" in next.config.js. The Dockerfile above assumes standalone output. Without it, the build artifact is much larger and the COPY --from=build /app/.next/standalone line fails.
A .dockerignore listing node_modules. COPY . . runs after the clean install is copied in, so without one your local node_modules overwrites it.

What’s next

Auth, full reference

Identity headers, access policies, and access modes in detail.

Multi-service routing

Deploy Next.js alongside a FastAPI or Express backend with shared origin.

Environment variables

Build-time vs runtime env vars, secrets, and per-service scoping.

Custom domains

DNS, verification, multi-service routing.

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Build a Next.js app on floo

Before you start

1. Add a Dockerfile

2. Build-time env vars (`NEXT_PUBLIC_*`)

3. Initialize the floo config

4. Connect the repo and deploy

5. Add a Postgres database

6. Add per-user auth

7. Add a custom domain

8. Local development with dev credentials

Common gotchas

What’s next

Auth, full reference

Multi-service routing

Environment variables

Custom domains

​Before you start

​1. Add a Dockerfile

​2. Build-time env vars (NEXT_PUBLIC_*)

​3. Initialize the floo config

​4. Connect the repo and deploy

​5. Add a Postgres database

​6. Add per-user auth

​7. Add a custom domain

​8. Local development with dev credentials

​Common gotchas

​What’s next

Auth, full reference

Multi-service routing

Environment variables

Custom domains

Before you start

1. Add a Dockerfile

2. Build-time env vars (`NEXT_PUBLIC_*`)

3. Initialize the floo config

4. Connect the repo and deploy

5. Add a Postgres database

6. Add per-user auth

7. Add a custom domain

8. Local development with dev credentials

Common gotchas

What’s next