# Deploy Doctor

> Diagnose and fix common web-app deployment failures — especially full-stack JS apps (Vite SPA + Express/Node + serverless). Covers "the site shows raw JavaScript source", FUNCTION_INVOCATION_FAILED on Vercel, Render/Railway port-binding failures, env vars that don't take effect, missing build dependencies, blank social link previews, and SPA routing 404s. Use when a deploy "succeeds" but the site…

- **Type:** Skill
- **Install:** `agentstack add skill-yahiasherif002-claude-skills-deploy-doctor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Yahiasherif002](https://agentstack.voostack.com/s/yahiasherif002)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Yahiasherif002](https://github.com/Yahiasherif002)
- **Source:** https://github.com/Yahiasherif002/claude-skills/tree/master/deploy-doctor

## Install

```sh
agentstack add skill-yahiasherif002-claude-skills-deploy-doctor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Deploy Doctor

A diagnostic playbook for the deployment failures that look mysterious but have well-known causes.
Match the **symptom**, apply the **fix**.

## 🔴 Site serves raw JavaScript / shows the bundled server source
**Cause:** an Express/Node app with `server.listen()` was deployed to a **serverless/static** host
(Vercel/Netlify). They don't run a persistent server — they served your built `dist/index.js` as a
static file.
**Fix — pick one:**
- **Node host (simplest):** deploy to Render/Railway/Fly/DO App Platform. Build `npm run build`,
  start `npm start`. The Express server serves the SPA + API in one process.
- **Stay serverless:** serve the SPA statically (`outputDirectory: dist/public`) and move API
  routes into serverless functions (`/api/*`). Don't ship the long-running server.

## 🔴 `FUNCTION_INVOCATION_FAILED` (Vercel) / function 500s on *every* request (even GET)
**Cause:** the function **crashes on load** — most often an **extensionless relative import**
(`import x from "./util"`) under Vercel's per-file ESM compilation → `ERR_MODULE_NOT_FOUND`.
**Fix:** make the function **self-contained (zero imports)**, or use explicit `.js` extensions on
relative imports. Also wrap the handler in `try/catch` so real errors return JSON instead of a
platform crash. Test: `GET` should return your `405`, not a platform 500.

## 🔴 Render/Railway: "deploy live" but unreachable / "no open ports"
**Cause:** the app doesn't bind the platform's `$PORT`, or hunts for a "free" port.
**Fix:** in production bind **exactly** `process.env.PORT` on host `0.0.0.0`:
```ts
const port = Number(process.env.PORT) || 3000;
server.listen(port, "0.0.0.0");
```
Don't run a "find an available port" loop in prod.

## 🔴 Build fails: "vite: not found" / "esbuild not found"
**Cause:** the host sets `NODE_ENV=production`, so `npm/pnpm install` skips **devDependencies**
(where vite/esbuild/tsx live).
**Fix:** force dev deps for the build: `pnpm install --prod=false` (or `npm ci --include=dev`).

## 🔴 Env vars / API keys "set" but the app acts like they're missing
**Causes & fixes:**
- Env vars only apply at **build/start of a NEW deploy** — after adding them, **redeploy**.
- Your **`.env` is gitignored and NOT deployed** — set the vars in the host's dashboard, not just locally.
- **Client vs server:** only `VITE_`/`NEXT_PUBLIC_`-prefixed vars reach the browser; secrets must
  stay server-side (functions / server env).
- **Name mismatch** — confirm the exact key names.

## 🔴 Blank/ugly social link previews (LinkedIn/Twitter/Slack)
**Cause:** `og:image` / `og:url` are **relative paths**; crawlers need absolute URLs.
**Fix:** use `https://domain/og-image.png` (absolute), a 1200×630 image, `summary_large_image`.
LinkedIn caches — re-scrape via the Post Inspector. (See the `seo-kit` / `og-image` skills.)

## 🔴 SPA routes 404 on refresh / direct link (e.g. /projects/foo)
**Cause:** no SPA fallback — the host looks for a real file at that path.
**Fix:** rewrite all non-asset, non-API paths to `/index.html`. Vercel:
```json
{ "rewrites": [{ "source": "/((?!api/).*)", "destination": "/index.html" }] }
```
(Static assets are served by the filesystem first; the `(?!api/)` keeps serverless functions working.)

## 🔴 Stray horizontal scrollbar / layout drifts below the fold
- `overflow-y: auto` silently promotes the **other axis to `auto`** too → add `overflow-x: hidden`.
- A fixed full-height shell should be `h-screen` + `overflow-hidden`, not `min-h-screen`
  (which can grow past the viewport and leave gaps).

## General checklist
1. Does it build locally? `npm run build && npm start`.
2. Right host for the architecture? (persistent server → Node host; static+functions → serverless)
3. Env vars set **in the host**, and **redeployed** after?
4. Functions: self-contained, wrapped in try/catch, bind `$PORT` (servers)?
5. SPA fallback + absolute OG URLs configured?

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yahiasherif002](https://github.com/Yahiasherif002)
- **Source:** [Yahiasherif002/claude-skills](https://github.com/Yahiasherif002/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yahiasherif002-claude-skills-deploy-doctor
- Seller: https://agentstack.voostack.com/s/yahiasherif002
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.