Frameworks

Node.js on Stackap

Stackap runs any Node.js app that has a start script: it installs dependencies, runs your build if you have one, and starts the app as a non-root process that must listen on the port it is given.

How Stackap recognizes Node.js

Node is the last test, tried after Next.js, the static-output frameworks and a plain index.html. A project qualifies when package.json has a start script. A repository with an index.html and no start script is served as a plain static site instead. If none of these match and there is no Dockerfile, the build is refused with the reason.

What Stackap builds

The generated image installs dependencies with npm, Yarn or pnpm depending on the lockfile, runs the build script when one exists, and runs npm start as an unprivileged user. Your app must listen on the port passed in the PORT environment variable, not a number you hard-coded.

Health is judged by an HTTP request. By default Stackap asks the app's port for a successful response on a default path. An API with no page at the root should be given its own port and health path in project settings, for example port 8080 and /healthz, which is the combination that was tested with a toy API.

What a Node.js project needs

• A start script that starts a server and does not exit.
• The app reads PORT from the environment.
• A health route that returns a success status when the app is ready.
• Secrets only in environment variables set through Stackap, never in the repository.

Verification status

Tested with real Docker builds of the generated Node image and, live on the server, with a toy API-only app that was refused with default settings and served correctly once given a port and health path.

Still to verify: long-running workers with no HTTP port, WebSocket-heavy apps, apps that need system packages beyond what the base image has, or any particular framework such as Express or Fastify (they should behave as Node apps, but we have not run each).

Early-access scope

• The app must serve HTTP. A background worker with no port cannot pass a health check today.
• One container per copy and no sidecars. Anything that needs a second process alongside the first needs its own Dockerfile.
• Server-rendering frameworks such as Remix, Nuxt and SvelteKit are not recognized by name. They might run as Node apps with a start script, but that is untested and we do not claim it.
• There is no persistent disk for the container. Files written at runtime are lost on the next deploy, so use the database or object storage.

Questions

Last updated 2026-10-03.