Docs menu
Deploying Next.js
Deploy a Next.js app on Primcloud: Procfile, environment variables, standalone output, and runtime notes.
On this page
Next.js deploys like any Node.js app: build with next build in your build script and run next start from a Procfile. This page covers the Procfile, the environment variables Next.js expects, standalone output, and what to know at runtime.
Starter template#
The Vercel create-next-app scaffold works with no modifications beyond adding a Procfile and pinning engines.node:
npx create-next-app@latest my-app
cd my-app
Then add the two files below, commit, and import into Primcloud.
Procfile for Next.js on Primcloud#
web: next start -p $PORT
Important
Pass -p $PORT. Without it, Next.js listens on 3000 and gets no traffic.
With output: 'standalone' (see Framework gotchas below), the launch command changes:
web: node .next/standalone/server.js
The standalone server.js reads $PORT on its own, no flag needed.
Background workers. If you run any background work (queued jobs) as separate processes, add a worker line:
web: next start -p $PORT
worker: node dist/worker.js
Each line is its own formation, scaled separately.
Env vars this framework expects#
Set these as secrets.
Required-ish:
NODE_ENV=production: Next automatically sets this internally, but any code you write should also treat production as the default. Setting it explicitly makes intent clear.- Any
NEXT_PUBLIC_*values your components read. These are built into the client bundle bynext build, so set them before the deploy that builds them. Saving a secret redeploys without rebuilding, so after changing one, push or start a manual deploy to rebuild.
Common:
NEXTAUTH_URL/NEXTAUTH_SECRET: required if you're using NextAuth / Auth.js.NEXTAUTH_URLshould match your production domain.DATABASE_URL: Prisma, Drizzle, and anything else expects it under this name by convention.NEXT_TELEMETRY_DISABLED=1: opts out of Next.js's build-time telemetry ping.
Runtime vs. build-time. Next.js exposes only NEXT_PUBLIC_* variables to client code, and it does so at build time. The values are inlined into the JS bundles when next build runs. Server-side code (route handlers, server components, getServerSideProps) reads any env var at runtime.
Framework gotchas on Primcloud#
Standalone output.
Next.js's standalone mode traces exactly which files your app needs at runtime and outputs a minimal Node.js server:
module.exports = {
output: "standalone",
};
With this on, next build produces .next/standalone/, a self-contained runtime folder that includes server.js, your compiled code, and only the node_modules your app actually imports. The launch command becomes node .next/standalone/server.js.
It leaves out everything your app doesn't import, which makes a large app much smaller than the full node_modules. You'll also need to copy the public/ and .next/static/ directories into the standalone tree. Next.js doesn't do this automatically. Add a heroku-postbuild step:
{
"scripts": {
"build": "next build",
"heroku-postbuild": "cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/"
}
}
Static assets and the public/ directory.
Files in public/ are served by Next.js at the root path. On standalone builds, you must copy public/ into .next/standalone/ as above. Next.js's default next start handles this automatically, standalone does not.
Image optimization.
Next.js's <Image> component optimizes images on request, in your Node.js process, using its CPU and memory. Two options:
- Keep it on. Optimized images are cached in
.next/cache/images/on local disk, which is wiped on every restart and deploy, so each image is optimized again the first time it's requested after one. - Use
next.config.jsimages.unoptimized: trueto disable optimization entirely and let the browser handle sizing.
Middleware and Edge runtime.
middleware.ts runs on Node.js. Primcloud has no Edge runtime, so middleware that depends on Edge-only APIs, like Vercel's waitUntil, won't work.
Build memory.
next build on a large app can use several GB of memory for type-checking and bundling. If the build runs out, add a NODE_OPTIONS=--max-old-space-size=4096 secret.
Troubleshooting#
Build fails at Type error:: Next.js runs the TypeScript compiler as part of next build. Fix the error, or set typescript.ignoreBuildErrors: true in next.config.js (not recommended; hides real bugs).
Client requests hit a 500 with Application error: a server component or route handler threw. Check Logs for the stack trace, then reproduce locally with npm run build && npm start (not npm run dev, since dev mode surfaces different errors).
NEXT_PUBLIC_* env var changed but the client still sees the old value: they're built in when the app builds. Push a commit or start a manual deploy to rebuild.
next start binds to port 3000 instead of $PORT: you forgot the -p $PORT flag in the Procfile, or you're on standalone output and using next start instead of node .next/standalone/server.js.
Standalone output can't find public/ or .next/static/: you didn't copy them into .next/standalone/ in heroku-postbuild. See the snippet in Framework gotchas.