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:

Terminal
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#

Procfile
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:

Procfile
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:

Procfile
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 by next 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_URL should 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:

next.config.js
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:

package.json
{
  "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.js images.unoptimized: true to 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.