# How to deploy a Node.js app Listen on the port in `PORT`, add a `start` script to `package.json`, and upload the app to a host that runs `npm start`. The host routes HTTPS to that port. **On Runtime, an [App](/docs/apps) is a Linux machine that keeps your app in `/app` running on port 8080. It starts the app the way Heroku and Render do: the Procfile's `web:` line, else `npm start`.** An App never pauses, so it is billed for its memory the whole time it runs, at $0.008 per GB-hour, plus $0.03 per vCPU-hour of CPU it uses ([pricing](/docs/pricing)). ## Get the app ready Every host that runs Node.js apps makes the same few demands. An app that meets them moves between hosts without changes. | What the host needs | How to give it | | --- | --- | | A port to send traffic to | Listen on `process.env.PORT`, with a default for your laptop | | A way to start the app | A `start` script in `package.json`. With none, npm runs `node server.js` | | The same dependencies every time | Commit `package-lock.json`, and install with `npm ci` | | A known Node.js version | An `engines` field, such as `"node": ">=22"` | | Configuration outside the code | Read keys and URLs from environment variables, never from committed files | | A clean stop | Handle `SIGTERM`: stop taking requests, finish the ones in flight, then exit | A minimal server that meets them: ```js const http = require("node:http"); const port = Number(process.env.PORT ?? 8080); const server = http.createServer((req, res) => res.end("ok\n")); server.listen(port, () => console.log(`listening on ${port}`)); process.on("SIGTERM", () => server.close(() => process.exit(0))); ``` Listen on all interfaces, which is what `listen(port)` does with no host. A server bound to `127.0.0.1` answers on your laptop but not behind a host's router. ## Deploy it on Runtime This script creates an App, writes `package.json` and `server.js` to `/app`, restarts the App's server so it runs them, and calls the app through a [preview](/glossary/preview-url), an HTTPS address for the port. It uses `curl` and `jq` against the [API](/docs/reference/apps), with your key in `RUNTIME_API_KEY`. ```bash check api=https://api.withruntime.com/v2 auth="Authorization: Bearer $RUNTIME_API_KEY" # An app's machine starts the app in /app the way Heroku does: npm start. app=$(curl -sf -X POST "$api/apps" -H "$auth" -H "Content-Type: application/json" -d '{}' | jq -r .id) trap 'curl -sf -X DELETE "$api/apps/$app" -H "$auth" > /dev/null' EXIT printf '{"scripts":{"start":"node server.js"}}' | curl -sf -X PUT "$api/apps/$app/files?path=/app/package.json" -H "$auth" \ -H "Content-Type: application/octet-stream" --data-binary @- > /dev/null cat <<'JS' | curl -sf -X PUT "$api/apps/$app/files?path=/app/server.js" -H "$auth" \ -H "Content-Type: application/octet-stream" --data-binary @- > /dev/null const http = require("node:http"); const port = Number(process.env.PORT ?? 8080); http.createServer((req, res) => res.end(`hello from Node ${process.version}\n`)).listen(port); JS # Restart the app's server so it runs the new code. curl -sf -X POST "$api/apps/$app:exec" -H "$auth" -H "Content-Type: application/json" \ -d '{"cmd": "sudo pkill -f runtime-app || true; sudo -E -u runtime runtime-app", "wait": false}' > /dev/null preview=$(curl -sf -X POST "$api/sandboxes/$app/previews" -H "$auth" \ -H "Content-Type: application/json" -d '{"port": 8080}') url=$(jq -r .url <<< "$preview") token=$(jq -r .token <<< "$preview") curl -sf --retry 40 --retry-all-errors --retry-delay 1 "$url" -H "x-runtime-preview-token: $token" # hello from Node v... ``` The `trap` deletes the App when the script ends. Leave it out to keep the app running. A private preview needs its token in the `x-runtime-preview-token` header. For a real project, upload the whole folder instead of single files, then run `npm ci` in `/app` before the restart. ## Mistakes to avoid - **A hard-coded port.** `listen(3000)` works on your laptop and fails on a host that routes to another port. Read `PORT`. - **Dependencies from `npm install`.** It can resolve newer versions than you tested. `npm ci` installs exactly what the lockfile says, and fails if the lockfile and `package.json` disagree. - **Secrets in the repository.** A `.env` file committed once stays in the history. Give the host the values as environment variables or [secrets](/how-to/use-secrets-in-a-sandbox). - **Work that dies with the request.** A host may restart the process at any time. Keep sessions and uploads in a database, an object store or a volume, not in memory or on the local disk alone. ## Related - [What is a platform as a service (PaaS)?](/glossary/platform-as-a-service) - [How to deploy an HTTP function](/how-to/deploy-an-http-function), for a handler that pauses between requests - [How to deploy a Docker container](/how-to/deploy-a-docker-container), when the app already ships as an image - [How to add a custom domain](/how-to/add-a-custom-domain) ## Sources - [npm Docs, scripts](https://docs.npmjs.com/cli/v11/using-npm/scripts), checked 17 November 2026 - [Node.js, HTTP](https://nodejs.org/api/http.html), checked 17 November 2026 - [Heroku Dev Center, The Procfile](https://devcenter.heroku.com/articles/procfile), checked 17 November 2026 Facts on this page were checked on 17 November 2026.