Build a Next.js app on floo

​

1. Add a Dockerfile

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

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"]

​

2. Build-time env vars (NEXT_PUBLIC_*)

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

# 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

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

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

​

3. Initialize the floo config

floo init my-nextjs-app

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

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

​

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

floo apps show my-nextjs-app

​

5. Add a Postgres database

[managed.default]
type = "postgres"

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

​

Optional: add file storage

[managed.uploads]
type = "storage"

[services.web.env]
managed = ["postgres", "storage:uploads"]

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

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

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

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

​

7. Add a custom domain

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

gh release create v1 --repo <owner>/<repo>
floo domains show app.example.com --app my-nextjs-app

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

​

8. Local development with dev credentials

floo dev --app my-nextjs-app

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

​

Faster pushes

• Run npm run build (or next build) as its own RUN line, as in the Dockerfile above. floo then keeps .next/cache between pushes, so Next.js recompiles only what changed. A cd, a comment, a heredoc, or the exec form (RUN ["npm", "run", "build"]) on that line turns this off.
• Keep "incremental": true in tsconfig.json. create-next-app sets it. With it, type checking reuses the previous push’s results from .next/cache.
• Copy package.json and the lockfile before the source, as in the deps stage above. npm ci then reruns only when the lockfile changes. A push that changes dependencies also produces a larger new image layer, so it takes longer to build and to start.
• In the final stage, copy anything that rarely changes before .next/standalone, such as a full node_modules for a migration tool. A layer after a changed one is rebuilt and uploaded on every push. See Layer order.

​

Build files from the edge cache

• Only public apps are cached. An app behind sign-in or an edge policy gets private on every response, and the cache stores nothing for it. See Caching signed-in responses.
• When an app stops being public, gains an edge policy, or loses a host, floo clears that host’s cached files.
• Requests to /_next/static/* bill as edge cache requests, and files served from the cache bill as edge cache bandwidth. Rates are on getfloo.com/pricing. Cache hits are not counted in floo analytics.

​

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.

​

Next steps