Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: Node App with a Pipeline

Ship a small Node.js app through a full Heroku pipeline: package.json engines and start script, app.json for CI and review apps, staging, promotion and a graceful shutdown.

This project takes a minimal Node.js web service and wires it into the full workflow from this chapter: GitHub, CI, review apps, staging and production. You will write the files that Heroku reads, and practice the logic of the app and of the pipeline with runnable stand-ins. The Heroku platform itself cannot run on this site, so all heroku commands are read-only text.

Overview

flowchart LR
    PR["Pull request"] --> CI["Heroku CI<br/>npm test"]
    PR --> RV["Review app"]
    CI -->|"green + merge"| STG["Staging<br/>auto deploy main"]
    STG -->|"manual promote"| PRD["Production"]

Pull requests get CI and a review app; main flows to staging automatically and to production on purpose.

The files Heroku needs

package.json:

JSON
{
  "name": "status-board",
  "version": "1.0.0",
  "private": true,
  "engines": { "node": "24.x" },
  "scripts": {
    "start": "node server.js",
    "test": "node --test"
  },
  "dependencies": {}
}
  • engines.node tells the Node.js buildpack which major version to install; use the current LTS and a range (24.x) rather than an exact version, so security patches arrive.
  • scripts.start is what the default web process runs when you have no Procfile. You can still add a Procfile with web: npm start.
  • Heroku runs npm ci or npm install and, if present, npm run build. Put devDependencies you need only for tests there; they are pruned afterwards.
  • Commit your lock file (package-lock.json) so builds are reproducible.

server.js (read-only sketch; it uses only Node's standard library):

JavaScript
const http = require("node:http");

const server = http.createServer((req, res) => {
  if (req.url === "/health") {
    res.writeHead(200, { "Content-Type": "application/json" });
    return res.end(JSON.stringify({ status: "ok" }));
  }
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end(`Hello from ${process.env.APP_ENV || "local"}\n`);
});

server.listen(process.env.PORT || 3000);

process.on("SIGTERM", () => {
  server.close(() => process.exit(0));
});

Two details matter on Heroku: listen on process.env.PORT, and shut down cleanly on SIGTERM (Heroku sends it on every restart, deploy and daily cycle, then kills the process after 30 seconds).

The handler as a pure function

To test logic without a server, write the route handling as a function from request path to {status, body}. The browser JavaScript runner executes this one.

JS A testable request handler

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The same code gives different greetings in each environment only because of the APP_ENV config var; the code is identical (pipelines).

app.json for CI and review apps

JSON
{
  "name": "status-board",
  "env": {
    "APP_ENV": { "value": "review" }
  },
  "formation": { "web": { "quantity": 1, "size": "basic" } },
  "buildpacks": [{ "url": "heroku/nodejs" }],
  "environments": {
    "test": {
      "scripts": { "test": "npm test" }
    }
  }
}

The env block gives review apps APP_ENV=review; the test environment tells Heroku CI how to run tests. There is no database in this project, so no add-ons are needed, which also makes review apps cheap. See review apps for postdeploy.

Create the pipeline

Terminal
heroku create status-board-staging
heroku create status-board-prod
heroku pipelines:create status-board --app status-board-staging --stage staging
heroku pipelines:add status-board --app status-board-prod --stage production
heroku pipelines:connect status-board --repo yourname/status-board
heroku config:set APP_ENV=staging --app status-board-staging
heroku config:set APP_ENV=production --app status-board-prod

Then, in the pipeline page of the dashboard: enable Review Apps, enable Automatic deploys for main on staging with "Wait for CI to pass before deploy", and leave production manual. Heroku app names are global, so pick names of your own.

Simulate the flow

The stand-in below models the pipeline with plain dictionaries so you can see how a change moves, what is rebuilt and what is not.

Python Stand-in: pull request to production

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The broken change is stopped by CI; the fixed one reaches staging and is promoted unchanged to production.

Graceful shutdown, tested

A frequent production bug is a process that ignores SIGTERM, which produces the R12 exit-timeout code and abrupt connection drops. The logic is "stop accepting new work, finish the current work, then exit". Try it as a simulation:

JS Stand-in: graceful shutdown

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Release checklist for this project

  1. Pull request opened: CI green and review app opened and clicked through.
  2. Merged: staging redeployed automatically; run the smoke test against staging.
  3. Promote to production; watch heroku logs --tail and the Metrics tab for a few minutes (router metrics).
  4. If errors appear, heroku releases:rollback (troubleshooting).

Ideas for extending it

  • Add Postgres in staging and production and postdeploy seed data for review apps.
  • Add a release script that runs migrations.
  • Add a worker process and scale it separately (scaling).
  • Add alerting on 5xx rates (logging).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does engines.node in package.json do on Heroku?

    The buildpack reads engines.node to choose the Node version; a range like 24.x allows patch updates.
  2. 2. Why does production stay on manual promotion in this project?

    Auto deploys to staging give fast feedback; a human promotes the tested slug to production.
  3. 3. What should the server do on SIGTERM?

    Graceful shutdown within 30 seconds avoids dropped requests and R12 errors.
  4. 4. How does the same code behave differently in staging and production?

    The slug is identical; the environment's config vars supply the differences.

Summary

  • Node apps need engines, a start script and a server bound to process.env.PORT.
  • app.json configures review apps and the CI test script.
  • Create staging and production apps, add them to a pipeline, auto deploy staging and promote to production.
  • Handle SIGTERM gracefully and watch metrics after every promotion.

Next: Practice: Production Readiness Checklist