The short answer
To deploy a Next.js app as a server, use next build and then next start. Do not use next dev. Treat NEXT_PUBLIC_ as public and fixed in that build. Check build memory and what replicas do not share before you scale.
The Next.js framework recipe on Unbroker requires Pro, with enough memory for the build and for the running server. The guide does not publish a number for that memory. The steps are Deploy Next.js and Deploy a Next.js application.
A server, or a static export
Choose the Next.js preset when the app needs a running server. A static export is a different shape. Next.js turns it on with output: 'export' in next.config.js. next build then writes an out folder of HTML, CSS, and JavaScript.
That export does not provide features that need a server at request time. Next.js lists cookies, server actions, incremental static regeneration, redirects, and route handlers that read the incoming request among the unsupported features. A route handler in an export can emit a static GET only if you mark it dynamic = 'force-static'. The source is Next.js static exports.
Unbroker’s guide says the same split: a static export produces files and cannot provide request-time server features. This page does not describe a separate Free recipe for a Next.js export. Free includes static HTML and static React, Vue, Vite, and Astro sites, plus managed Node.js. Other framework recipes, including the Next.js one, are Pro. Astro’s preset serves the generated files, and a server adapter is a separate deploy. That decision is Astro hosting.
The scripts that matter
The guide’s production scripts are:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start --hostname 0.0.0.0"
}
}
next build creates the production build. next start runs it. next dev is the development server. A bare next command is an alias for next dev, so it is not a production start. The CLI reference is the Next.js CLI.
next start reads PORT. The CLI default port is 3000, and -p or --port overrides it. Next.js says PORT cannot be set in .env, because the HTTP server starts before that file is read. A platform variable named PORT is not that file.
The CLI lists --hostname defaulting to 0.0.0.0 for next start. Unbroker’s sample script passes the flag anyway. If you use standalone output or a custom server, match the start command to that output. The guide does not name a replacement command.
Run the locked install, the build, and the start locally. Test a dynamic route as well as the homepage.
Public build variables and runtime secrets
NEXT_PUBLIC_ is for browser code. Treat it as public. Unbroker selects public build variables, including NEXT_PUBLIC_* and VITE_*, for the target environment before the build. A change that is already inside the frontend needs a new build. How scopes work is Environment variables and secrets.
Private variables stay runtime-only, except the documented package-registry credentials. Do not make static generation depend on a production secret that is missing during the build. Move that work to request time, or use a build process designed for it.
Variables are All, Production, or Preview. A new preview copies All and Preview, not Production-only values. Redeploy after a runtime change so the running revision picks it up.
When the build runs out of memory
Look at where the build failed: dependency installation, compilation, or page generation. Reduce work the build does not need, or change the capacity that applies to that stage. Extra runtime replicas do not fix a build that already ran out of memory.
The docs do not publish a memory threshold for that failure. The recipe still asks for enough memory for the build and for the runtime. If the process is already running and then fails, that is a different stage. How to read the right log is Debug a failed deployment.
More than one replica
Replicas do not share process memory or local files. Review sessions, caches, uploaded files, and any generated state before you add a replica. Put data that must match across replicas in a database or another shared store.
A service with a persistent volume stays single-replica. The volume can grow up to 50 GB and cannot shrink. Deleting the service deletes the volume. That limit is persistent volumes. How the replica count changes is Replica autoscaling. Free services run one replica. Configurable replicas are Pro.
Check more than the homepage
Open the URL Cloud gives you. Check a server-rendered page, an API route if you have one, authentication callbacks, and static assets. Update callback allowlists with the deployed origin. A homepage that renders does not exercise the whole app.
A custom domain is a separate step from the first URL. DNS and the certificate are Custom domain and HTTPS. Which push produced the revision is Deploy on git push.
How this works on Unbroker
Create a repository service, select Next.js, and review the branch, the build command, and the start command. Set public variables before the build. Add private credentials in Variables.
The Next.js recipe requires Pro. Pro is $25 per month with $25 of usage credit. The credit does not roll over. If usage stays under the credit, the charge is still $25. The cluster, the volume, and the build are separate from that fee. Plan rows are on pricing and in Plans.
A frontend and an API in one project is frontend and API. An app that started in another tool and still points at that tool’s database is an AI-built app in production.
Checklist
- Set
buildtonext buildandstarttonext start, notnext dev. - Pass
--hostname 0.0.0.0as the guide’s script does, even though the current CLI default is the same host. - Let the platform supply
PORT. Do not rely onPORTinside.env. - Put
NEXT_PUBLIC_values in before the build, and rebuild when they change. - Keep production secrets out of static generation.
- If the build runs out of memory, name the stage before you add runtime replicas.
- Before a second replica, move sessions, caches, and uploads to a shared store. A volume keeps the service at one replica.
- Request a server-rendered page, an API route, and an auth callback on the deployed origin.
- Use Pro for the Next.js recipe. Do not treat the Free Node.js recipe as this preset.
FAQ
Should you use next dev in production?
No. next dev is the development server, with hot reload. The production path is next build, then next start. The Next.js CLI treats a bare next command as an alias for next dev. Unbroker's Next.js guide says not to use next dev as the production start command.
Why doesn't a NEXT_PUBLIC_ variable update after you change it?
NEXT_PUBLIC_ values are for browser code. Unbroker selects public build variables, including NEXT_PUBLIC_ and VITE_, for the target environment before the build and embeds them in the frontend. Changing one requires a new build. Other variables stay runtime-only, except package-registry credentials.
Can you use a secret during next build?
Do not make static generation depend on a production secret that is not available during the build. Unbroker keeps private variables runtime-only. Move that work to request time, or use a build process designed for it. A value with the NEXT_PUBLIC_ prefix is public even if you typed it in Variables.
Why does a Next.js build run out of memory?
Look at the stage that failed: dependency installation, compilation, or page generation. Reduce build work you do not need, or adjust the capacity that applies to that stage. Extra runtime replicas do not fix a build that ran out of memory. The docs do not publish a memory number for that failure.
Can you run Next.js on more than one replica?
Replicas do not share process memory or local files. Review sessions, caches, uploaded files, and generated state before you scale, and put shared state in a database or another shared store. A service with a persistent volume stays single-replica. Replica count is configurable on Pro. Free services run one replica.
Do you need a server, or can you export static files?
A running Next.js server is the preset when the app needs work at request time. output: 'export' writes an out folder of HTML, CSS, and JavaScript. Next.js does not support cookies, server actions, incremental static regeneration, or route handlers that read the request in that export. Unbroker treats a static export as a different shape from the server recipe.
Which port does next start listen on?
The Next.js CLI default is port 3000. next start reads the PORT environment variable, and -p or --port overrides it. Next.js says PORT cannot be set in a .env file, because the HTTP server starts before that file is read. The hostname flag defaults to 0.0.0.0. Unbroker's sample start script still passes --hostname 0.0.0.0.