@workingmodel/why-is-this-failing-in-prod

Tells you in plain English why your app works locally but breaks in production. Developed by Working Model.

why-is-this-failing-in-prod

Scanning: /Users/you/my-app
Node: v20.11.0

✖ [Environment] 2 env var(s) in .env.example have no local value: DATABASE_URL, JWT_SECRET
  → These are likely missing in prod too. Add them to your deployment environment.

⚠ [Build Output] dist/ exists locally but is in .gitignore — prod won't have it unless built in CI.
  → Make sure your CI/CD pipeline runs `npm run build` before starting the app.

✖ [Start Script] "start" script uses a TypeScript runner (tsx src/index.ts)
  → Build first, then start with node. Change to "start": "node dist/index.js"

Summary: 2 errors, 1 warning
Fix the errors above before deploying.

Install

npx @workingmodel/why-is-this-failing-in-prod

Or install globally:

npm install -g @workingmodel/why-is-this-failing-in-prod

Usage

Run in your project root:

why-is-this-failing-in-prod

Or point it at a specific directory:

why-is-this-failing-in-prod /path/to/my-app

Exits with code 1 if errors are found — pipe-friendly for CI.

What It Checks

| Check | What it catches | |-------|----------------| | Environment vars | Keys in .env.example missing from your local .env — likely missing in prod too | | Node version | Local Node doesn't satisfy your own engines.node range | | Build output | main points to dist/ but dist/ doesn't exist or is gitignored | | Start script | Missing start script, or start uses ts-node/tsx/nodemon in prod | | Local references | Hardcoded localhost addresses in npm scripts | | Platform fields | os or cpu fields that reject the current environment |

Why This Exists

You pushed. It deployed. It's broken. Your laptop is fine. The server is not. You've been staring at logs for forty minutes and the answer is a missing env var that was never in the deployment config because nobody wrote it down.

This tool is the checklist you should have run before pushing.

More tools from Working Model → workingmodel.co · npm @workingmodel