Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Add-ons and Config

app.json: The App Manifest

Describe a whole Heroku app in code with app.json: environment variables, add-ons, buildpacks, formation and scripts, and see how review apps and Heroku Buttons use it.

Creating an app by hand takes a dozen steps: create it, set the buildpacks, attach a database, set a handful of config vars, scale the dynos, run a setup script. Doing that once is fine. Doing it every time you want a fresh staging copy, a temporary app for a pull request, or an app for a new teammate is tedious and error-prone.

app.json is a manifest file in the root of your repository that describes the app's shape: what config it needs, which add-ons and buildpacks it uses, how to scale it and what to run after the first deploy. Heroku features such as review apps, CI runs and the "Deploy to Heroku" button read it to create a correct app automatically.

A complete example

JSON
{
  "name": "demo-shop",
  "description": "A small shop used in the Heroku tutorial.",
  "repository": "https://github.com/example/demo-shop",
  "keywords": ["shop", "demo"],
  "stack": "heroku-24",
  "buildpacks": [
    { "url": "heroku/nodejs" }
  ],
  "env": {
    "SECRET_KEY": {
      "description": "Signs session cookies.",
      "generator": "secret"
    },
    "LOG_LEVEL": {
      "description": "debug, info, warn or error.",
      "value": "info"
    },
    "STRIPE_KEY": {
      "description": "Payment API key (set in your own account).",
      "required": true
    }
  },
  "addons": [
    { "plan": "heroku-postgresql:essential-0" }
  ],
  "formation": {
    "web": { "quantity": 1, "size": "basic" }
  },
  "scripts": {
    "postdeploy": "npm run db:seed"
  }
}

The fields

Field Purpose
name, description, repository, logo, keywords Human-facing metadata shown by the Heroku Button and the dashboard
stack The stack the app should use
buildpacks Ordered list of buildpacks (url)
env The config vars the app wants, each with description, and value, required or generator
addons Add-ons to provision, by plan name
formation Process types with quantity and dyno size
scripts postdeploy runs once after an app is created from the manifest
environments Overrides for test (CI) and review (review apps)

How env entries behave:

  • value is a default that the new app starts with.
  • required: true makes the person creating the app supply the value (the button's form asks for it).
  • generator: "secret" produces a random secret string for you, ideal for session keys.
  • Each entry should have a description, because the form shows it to the person deploying.

Where it is used

  1. Review apps. A temporary app created for each pull request builds itself from app.json, which means the manifest decides its add-ons, config and post-deploy seeding. You can have different review settings in environments.review.
  2. Heroku CI. A test run uses environments.test to define the temporary environment: which add-ons and what script runs the tests.
  3. Deploy buttons. A "Deploy to Heroku" button in a README opens a form built from app.json so someone can launch their own copy in a couple of clicks.
  4. Documentation. Even if you use none of the above, the file is a readable summary of what the app needs.

postdeploy runs only once, when an app is first created from the manifest, so use it for seed data. Use the release phase for work that must happen on every deploy.

Environments for CI and review apps

JSON
{
  "environments": {
    "test": {
      "addons": ["heroku-postgresql:in-dyno"],
      "scripts": {
        "test": "npm test"
      }
    },
    "review": {
      "formation": {
        "web": { "quantity": 1, "size": "basic" }
      },
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Names such as heroku-postgresql:in-dyno (a database that lives inside the test dyno) exist for CI use; check the Dev Center schema for the current options before you copy them.

Stand-in: validate an app.json

Typos in the manifest silently change behavior, so a quick checker pays off. This stand-in parses JSON, checks a few rules and reports the config vars a person would have to supply.

Python Stand-in: check an app.json

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.

Stand-in: create an app from a manifest

This stand-in turns a manifest into the list of CLI commands you would otherwise type by hand. It demonstrates the central idea: the manifest is the declaration, and the commands are the steps that realize it. The secret is generated, so only its length is printed.

Python Stand-in: manifest to commands

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 real platform does these steps for you in one operation, in the right order, and it also knows how to wait for the build to finish before the postdeploy script runs.

Good practice

  • Keep app.json in sync with reality: when you add a config var to the code, add it to env with a description.
  • Never put real secrets in value; use required (the person supplies it) or generator.
  • Treat it like code: review changes to it in pull requests.
  • Keep heroku local's .env.example and the env section consistent so local and deployed apps ask for the same settings.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is app.json?

    app.json declares what an app needs so that apps (review apps, buttons, CI) can be created consistently.
  2. 2. What does generator: "secret" do for an env entry?

    The platform fills in a random secret string, which is useful for session or signing keys.
  3. 3. When does the postdeploy script run?

    postdeploy is for one-time setup, such as seeding. Use the release phase for per-deploy tasks.
  4. 4. Which feature uses app.json to build a temporary app per pull request?

    Review apps are created from the manifest so each pull request gets a correctly configured app.
  5. 5. Where should real production secrets be stored?

    app.json is committed to Git. Real secrets belong in config vars, supplied or generated at creation time.

Summary

  • app.json describes an app's metadata, stack, buildpacks, config vars, add-ons, formation and scripts.
  • env entries can have defaults, be required, or be generated as secrets.
  • Review apps, Heroku CI and deploy buttons read the manifest to create consistent apps.
  • Keep it accurate, reviewed and free of real secrets; use postdeploy for one-time setup only.

Next: Heroku Postgres Essentials