DeployScout

Catch dev-to-prod environment bugs before they bite you.

MERN apps routinely work perfectly in local development and break the moment they're deployed — not because of bad code, but because of environment assumptions that only become visible in a different environment. A hardcoded localhost URL, a CORS config scoped to your dev machine, a cookie setting that silently breaks cross-origin auth in production.

Generic linters won't catch these. They have no concept of "this string is fine locally and completely wrong in production." DeployScout does.

What it catches

CORS misconfiguration

• cors() package called with a hardcoded localhost origin — via both inline config objects and variable references
• Manual res.header("Access-Control-Allow-Origin", "http://localhost:...") calls

Hardcoded localhost URLs

• axios.get/post/put/delete/patch("http://localhost:...") calls
• fetch("http://localhost:...") calls
• io("http://localhost:...") socket connections
• Variable declarations with URL-like names pointing to localhost (BASE_URL, API_URL, BACKEND_HOST, etc.)

Why AST, not regex

DeployScout uses @babel/parser and @babel/traverse to parse files into an Abstract Syntax Tree rather than pattern-matching on raw text. This means it:

• Resolves variable references — detects cors(corsOption) where corsOption is declared elsewhere in the file, not just cors({ origin: '...' }) inline
• Understands code structure — distinguishes an actual CORS config object from a string that happens to contain localhost in a comment or unrelated variable
• Avoids false positives — the hardcoded-URL variable check only flags variables whose name suggests a URL or endpoint (URL, API, BASE, HOST, ENDPOINT, SERVER, BACKEND), not every string in the codebase

Installation

Run directly without installing:

npx deployscout <path-to-repo>

Or install globally:

npm install -g deployscout
deployscout <path-to-repo>

Usage

# Scan a repo
deployscout ./my-mern-app

# Scan a specific subfolder
deployscout ./my-mern-app/backend

DeployScout walks all .js and .jsx files under the given path, skipping node_modules, dist, and build automatically.

Example output

Scanning /path/to/my-mern-app...

Found 2 issue(s):

 CRITICAL  backend/index.js:8
  origin: 'http://localhost:3000',
  CORS origin is hardcoded to "http://localhost:3000". This will reject every
  real production frontend URL — the deployed frontend's origin will never
  match "localhost", so every cross-origin request will be blocked by the browser.
  AI: The corsOption origin is set to http://localhost:3000, which is only valid
  during local development. Once deployed, your frontend will run on a different
  domain and all cross-origin requests will be blocked. Fix: origin: process.env.FRONTEND_URL

 CRITICAL  frontend/src/hooks/useGetUsers.js:12
  const res = await axios.get("http://localhost:8080/api/v1/user/");
  This axios.get() call is hardcoded to "http://localhost:8080". In production,
  your backend will be hosted at a different domain — this call will fail with
  a connection error once deployed.
  AI: Replace with: const res = await axios.get(`${process.env.REACT_APP_BACKEND_URL}/api/v1/user/`);

DeployScout exits with a non-zero status code when critical findings are present, making it usable in CI pipelines.

AI-powered explanations (optional)

If a GEMINI_API_KEY is set, DeployScout enriches each finding with a context-specific explanation and suggested fix generated by Gemini — referencing the actual variable names and code patterns in your file, not a generic template.

# .env or environment
GEMINI_API_KEY=your_key_here

Get a free API key at aistudio.google.com/apikey — no credit card required.

If GEMINI_API_KEY is not set, DeployScout still runs and prints built-in explanations for every finding. The AI layer is an enhancement, never a dependency.

Exit codes

| Code | Meaning | |---|---| | 0 | No issues found, or only warnings | | 1 | One or more critical findings detected |

Project layout

src/
├── cli.js              entry point, wires everything together
├── scanner.js          walks the repo, finds candidate .js/.jsx files
├── explain.js          optional Gemini API explanation layer
└── rules/
    ├── cors.js         CORS misconfiguration detection
    └── hardcoded-url.js  hardcoded localhost URL detection

Current scope and known limitations

DeployScout is currently scoped to MERN (MongoDB / Express / React / Node) apps. It deliberately does not:

• Act as a general code reviewer
• Scan for dependency vulnerabilities (npm audit covers this)
• Detect committed secrets (gitleaks covers this)
• Support non-JS stacks in the current version

Known detection limitations in the current version:

• process.env.FRONTEND_URL || 'http://localhost:3000' (a || fallback with a localhost default) is not flagged — the value is a logical expression, not a plain string literal, and the fallback risk is considered a known v1 gap
• Variable-based CORS config (cors(corsOption)) is resolved one level deep; deeply nested or dynamically constructed config objects are not followed
• Manual CORS header checks assume the Express response object is named res or response

Background

DeployScout was built after personally losing hours to the exact bugs it now detects — deploying a real MERN chat app and hitting CORS errors, hardcoded localhost failures, and cookie cross-origin issues one after another. The tool exists because none of the existing linters or code reviewers understand the relationship between local dev assumptions and production deployment reality.