Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 37 ยท Getting Started

Deploy Your First App

Deploy a small Node.js web app to Heroku step by step: prepare the code, create the app, push with Git, open it, read the logs and fix the common first-deploy errors.

The best way to understand Heroku is to put something on it. This lesson walks through the shortest path from an empty folder to a live URL, using a tiny Node.js web server. The same steps work for any language; only the files that describe your dependencies change.

Remember that this site cannot reach your Heroku account, so the commands below are for your own terminal. They are shown without invented output: the CLI prints progress while building, and its exact wording changes between versions.

Step 1: write an app that fits the platform

Make a folder with three files. The first is the server. It must listen on the port Heroku provides in PORT:

JavaScript
// index.js
const http = require("node:http");

const port = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  res.setHeader("Content-Type", "text/plain; charset=utf-8");
  res.end("Hello from my first Heroku app!\n");
});

server.listen(port, () => {
  console.log(`Listening on ${port}`);
});

The || 3000 fallback lets you run the same file on your laptop. The second file declares the project and how to start it:

JSON
{
  "name": "first-heroku-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "engines": {
    "node": "22.x"
  }
}

The start script is how the Node.js buildpack knows what to run, and engines pins the major Node.js version (see stacks and runtime versions). The third file, .gitignore, keeps junk out of the repository:

TEXT
node_modules
.env

Test it locally with npm start, then open http://localhost:3000.

Step 2: put the code in Git

Heroku's classic deploy is a Git push, so the folder needs to be a repository with at least one commit:

CONSOLE
$ git init
$ git add .
$ git commit -m "First version"

Make sure your default branch is what you expect (git branch --show-current). Modern Git uses main; older setups use master, and the push command in step 4 must name the right one.

Step 3: create the app

CONSOLE
$ heroku create

With no name, Heroku generates a memorable one such as quiet-river-12345; with a name (heroku create demo-shop-yourname) you ask for it, and the name must be unique across all of Heroku, lowercase letters, digits and dashes only. The command does two things at once: it creates the app on the platform and adds a Git remote called heroku to your repository. Confirm the remote with git remote -v.

Step 4: push

CONSOLE
$ git push heroku main

Pushing starts a build. The output streams back to your terminal and tells you which buildpack was detected (Node.js here, because of package.json), what it installed, how big the resulting slug is and which release was created. When the push succeeds the app is already running.

If your local branch is called something else, push it to the remote's main: git push heroku mybranch:main. Heroku only builds from main (or master), so other remote branch names are ignored.

Step 5: open it and watch it

CONSOLE
$ heroku open
$ heroku logs --tail
$ heroku ps

heroku open launches the app's URL in your browser. heroku logs --tail streams the app's log lines, including your console.log output, until you press Ctrl+C. heroku ps lists the dynos and their state (up, starting, crashed). With no Procfile, the buildpack runs npm start as the web process and gives you one web dyno.

What the buildpack looked at

Heroku never asked you what language you were using. Each buildpack has a small detect step that looks for tell-tale files, and the first one that says yes wins. The stand-in below models that decision for a few popular languages. The real buildpacks are more careful (see buildpacks), but the principle is the same.

Python Stand-in: guess the buildpack from the files

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.

only-html has no dependency file, so nothing matches. That is exactly the situation that produces the "no default language could be detected" error on a real push.

Why binding to PORT matters

The most common first-deploy failure is a server that listens on a fixed port. Compare the two styles in a stand-in that reads the environment the way a real process would:

Python Stand-in: choosing the listening port

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.

When a process never binds the assigned port, the dyno is marked as crashed after the boot timeout, and the logs show an R10 Boot timeout error.

Troubleshooting the first deploy

Symptom Likely cause Fix
"Everything up-to-date" after push Nothing committed git add, git commit, push again
"No default language could be detected" No package.json, requirements.txt, etc. in the repo root Move the file to the root and commit it
Build succeeds, page shows "Application error" The process crashed or never bound $PORT Read heroku logs --tail
error: src refspec main does not match any Your branch is not called main git branch -M main or push master:main
H10 App crashed in logs The start command failed Run the same command locally and fix the error

Read the log first; the error code in it (H10, R10, H14 and so on) is documented in the Dev Center error-code list.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does heroku create do besides creating the app on the platform?

    The CLI registers a Git remote called heroku, which is why git push heroku main works afterward.
  2. 2. How does the Node.js buildpack know to use itself?

    Each buildpack has a detect step that checks for marker files; package.json signals Node.js.
  3. 3. Your server listens on port 3000 in production. What is the likely result?

    Only the port in $PORT is connected to the router. A hard-coded port is never reached and the dyno is reported as crashed.
  4. 4. Which command streams live log output?

    heroku logs --tail follows the log stream until you interrupt it.

Summary

  • A deployable app reads PORT, declares its dependencies in a file the buildpack recognizes, and lives in a Git repository.
  • heroku create makes the app and the heroku remote; git push heroku main builds and releases it.
  • heroku open, heroku logs --tail and heroku ps are your first tools for checking a deploy.
  • Most first-deploy failures are a missing dependency file, a wrong branch name or a hard-coded port.

Next: CLI essentials and reading logs