Build a Next.js app on floo

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

1. Add a Dockerfile

Configure standalone output, which makes a 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 . . copies 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 your code references 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 too. Two things have to line up. First, once step 4 has created the app, set the value as an ordinary env var. The name prefix is what makes it a build arg; no extra flag is needed.

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

Second, thread it through the build stage of the Dockerfile. ARG makes Docker accept the value; ENV 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

Step 4’s first deploy builds before the var exists. Once both are in place, rebuild:

floo redeploy --app my-nextjs-app --rebuild

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. When the values differ, set the var in prod too. The prod environment exists after the first promote; promote again to rebuild with the prod value:

floo env set NEXT_PUBLIC_API_URL=https://my-nextjs-app.getfloo.app --app my-nextjs-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

Install the CLI and sign in: curl -fsSL https://getfloo.com/install.sh | bash, then floo auth login. An agent can run the same journey over the HTTP API instead, starting from getfloo.com/agents.md.

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"

If your image includes a migration tool and its migration files, set migrate_command under [services.web]. It runs as a one-off job with the new image before traffic moves to it. A failed migration stops the deploy. Use expand-then-contract migrations to keep the schema compatible with both old and new code.

4. Connect the repo and deploy

floo builds from GitHub, not local files, so push first. floo apps github connect needs the floo GitHub App on the account that owns the repository, and opens a browser to install it if it is missing.

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.getfloo.app.Every git push origin main ships to dev. floo releases promote --app my-nextjs-app publishes to https://my-nextjs-app.getfloo.app.

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. Configure your database client to read it. For Prisma, follow the configuration for your installed Prisma version. Next.js standalone output does not automatically include the Prisma CLI, schema, or migration files. Include those in the runtime image and generate the client during the build before setting migrate_command = "npx prisma migrate deploy". The command must run from the packaged dependencies without downloading tools at deploy time.

File storage

Add [managed.uploads] with type = "storage", attach storage:uploads, and deploy. Configure the client in a server route; see Cloud storage for paygo restrictions and file operations. Keep keys server-side.

import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
  endpoint: process.env.STORAGE_S3_ENDPOINT_UPLOADS,
  region: process.env.STORAGE_S3_REGION_UPLOADS,
  credentials: { accessKeyId: process.env.STORAGE_S3_ACCESS_KEY_ID_UPLOADS, secretAccessKey: process.env.STORAGE_S3_SECRET_ACCESS_KEY_UPLOADS },
  requestChecksumCalculation: "WHEN_REQUIRED",
  responseChecksumValidation: "WHEN_REQUIRED",
});

6. Add per-user auth

Set access_mode = "accounts" and floo handles sign-in:

floo.app.toml

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

From the next deploy onward, floo’s gateway:

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>
  );
}

Locally, run floo dev --fixture-user (see section 8) or hit your dev server with curl -H 'X-Floo-User-Email: you@example.com'. Access modes and identity headers in full: Auth.

7. Add a custom domain

Declare the domain in floo.app.toml:

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

Commit and push, wait for that commit’s dev deploy to go live, then 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 that show prints, then watch activation:

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

Next.js reads Host and X-Forwarded-Host from the request, so it needs no extra config. DNS setup and troubleshooting: Custom domains.

8. Local development with dev credentials

floo dev --app my-nextjs-app

Runs dev_command locally with DATABASE_URL and readable env vars from the app’s dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Write-only secrets are withheld; supply separate local values when needed. Prod credentials never reach a local session. To test signed-in flows, add --fixture-user:

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

floo dev then puts a proxy in front of each accounts-mode service that injects the same X-Floo-User-* headers floo’s gateway adds in production. The output table shows the raw service URL and the auth-proxied URL; use 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, or 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

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

File storage

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

​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

​File storage

​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

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

File storage

6. Add per-user auth

7. Add a custom domain

8. Local development with dev credentials

Common gotchas

What’s next