Frameworks

Next.js on Stackap

Stackap recognizes a Next.js project from its dependencies, generates a Dockerfile for it, builds it on the server, and runs it as a small non-root container behind automatic HTTPS.

How Stackap recognizes Next.js

A project is treated as Next.js when its package.json lists next as a dependency. That check runs first, before any other framework test, so a Next.js app is never mistaken for a plain Node app because it also has a start script. If your repository contains its own Dockerfile, Stackap uses that and skips detection.

What Stackap builds

The generated Dockerfile builds the app in one stage and runs the result in a slimmer one, as an unprivileged user. The image for one real site came out at 164 MB.

Build-time variables follow a strict rule. Names beginning with NEXT_PUBLIC_ are passed in with their real values, because Next.js inlines them into the browser bundle and they are public by design. Every other variable is replaced by a placeholder during the build. That keeps secrets out of image layers, and it means code that reads a secret while the site is being statically generated sees the placeholder, so pages that need real data at build time have to fetch it when they are requested instead.

At runtime the container receives the real values through a private file. The container runs with no new privileges and with CPU, memory and process limits.

What a Next.js project needs

• A build script and a start script, which Next.js projects have by default.
• A lockfile. Stackap chooses npm, Yarn or pnpm from the lockfile it finds, and npm ci fails if the lockfile is stale.
• Public variables named NEXT_PUBLIC_*, set before you push, because they are baked in at build time and changing one later needs a new build.
• Image hosts declared in your Next.js config if you use remote images.

Verification status

Tested with real builds: a 31,592-page Next.js site builds on the server in about 96 seconds with a peak of roughly 2.8 GB of memory, serves the same pages as the live original (26 pages plus 64 sampled sitemap URLs compared), and passes a load test of about 410 requests per second with no errors on one copy, rising to roughly 700 with three copies on the 4-CPU box.

Still to verify: the Next.js image cache across restarts, incremental static regeneration across several servers (the cache is per server today), and Next.js features that depend on a vendor's edge network, such as edge middleware running at a distant location.

Early-access scope

• Only the generated single-container setup is supported. Splitting one Next.js app across several services is not.
• There is no edge network. Server-rendered pages come from one machine, which today is in Germany.
• Incremental static regeneration caches live on the server that rendered them, so running several copies on one box works but multi-server setups are not built.
• Variables that must be real at build time other than NEXT_PUBLIC_* are not supported by the placeholder rule.

Questions

Last updated 2026-10-03.