tpmjs/VERCEL_FIX_CHECKLIST.md

🔥 Vercel API Routes Fix - Action Checklist

Problem Summary

API routes are not deploying because Vercel is not detecting your project as Next.js.

When Vercel doesn't detect Next.js, it treats your deployment as a static site and drops all App Router API routes from the build output. Pages work because they're static files, but API routes require serverless function generation which only happens when Next.js is properly detected.

---

✅ Fix Checklist (Complete in Order)

1️⃣ Fix Root Directory

Where: Vercel Dashboard → Project tpmjs-web → Settings → General → Root Directory

Current (likely): Empty, ., or wrong path Required: apps/web (exactly this, no leading/trailing slashes)

Validation:

✓ Must be exactly: apps/web
✗ NOT: /apps/web/
✗ NOT: ./apps/web
✗ NOT: tpmjs/apps/web

---

2️⃣ Set Framework Preset

Where: Vercel Dashboard → Project tpmjs-web → Settings → General → Framework Preset

Current (likely): "Other" Required: "Next.js"

Why this matters:

• Framework = "Other" → Uses @vercel/static-builder → No API routes
• Framework = "Next.js" → Uses @vercel/next → API routes deployed

---

3️⃣ Remove Domain from Old Project

Where: Vercel Dashboard → Project v0-tool-registry-page → Settings → Domains

Action: Remove these domains:

• tpmjs.com
• www.tpmjs.com

Then: Verify both domains are ONLY assigned to the tpmjs project

Why this matters: The "Redirecting..." message is coming from the old project. Having two projects with the same domain causes shadow routing and API requests hitting the wrong deployment.

---

4️⃣ Clear Custom Build Commands

Where: Vercel Dashboard → Project tpmjs-web → Settings → Build & Development Settings

Set ALL to default/empty:

Build Command:     (empty - let Vercel auto-detect)
Install Command:   (empty - let Vercel auto-detect)
Output Directory:  .next (default)

Why this matters: Custom build commands bypass Vercel's Next.js detection. Vercel should automatically:

• Detect monorepo structure
• Run pnpm install
• Run pnpm build in the correct workspace
• Use @vercel/next builder

If you must use custom commands, use:

Build Command:     pnpm turbo run build --filter=@tpmjs/web
Install Command:   pnpm install

But try empty first.

---

🧪 Verification Steps

Before Deploying

Run this locally to confirm Next.js detection:

cd apps/web
vercel build

Expected output should include:

● route (app) /api/health
● route (app) /api/tools
● route (app) /api/sync/changes
λ /api/health
λ /api/tools
λ /api/sync/changes

If you DON'T see this, Vercel won't deploy API routes.

After Deploying

1. Check Build Output:

vercel inspect <deployment-url>

Should show:

Builds
  ├── λ api/health (XXX KB) [region]
  ├── λ api/tools (XXX KB) [region]
  ├── λ api/sync/changes (XXX KB) [region]
  ├── λ tool/[slug] (XXX KB) [region]
  ...

2. Test API Routes:

# Should return JSON (not timeout, not "Redirecting...")
curl https://tpmjs.com/api/health

# Should return tool data
curl https://tpmjs.com/api/tools

---

📋 Expected Results

✅ Success Indicators

• vercel inspect shows API routes as λ functions
• curl https://tpmjs.com/api/health returns JSON
• curl https://tpmjs.com/api/tools returns tool data
• No "Redirecting..." messages
• No timeouts on direct Vercel URLs
• Build logs show "route (app) /api/*"

❌ Failure Indicators (Need to revisit steps)

• Only pages listed in vercel inspect, no API routes
• API endpoints return "Redirecting..."
• API endpoints timeout (exit code 28)
• Build logs don't mention API routes
• Framework Preset still shows "Other"

---

🚨 Common Mistakes

Mistake 1: Wrong Root Directory Format

✗ /apps/web/  (leading/trailing slashes)
✗ ./apps/web  (relative path notation)
✗ apps/web/   (trailing slash)
✓ apps/web    (correct)

Mistake 2: Leaving Custom Build Commands

If you have:

{
  "buildCommand": "cd ../.. && turbo build --filter=@tpmjs/web"
}

This MIGHT work, but can break Next.js detection. Start with empty and only add if needed.

Mistake 3: Not Removing Domain from Old Project

If v0-tool-registry-page still has tpmjs.com, your requests will route to the wrong project randomly based on:

• DNS propagation
• Edge cache
• Vercel's routing priority

Mistake 4: Not Verifying Framework Preset

"Other" is Vercel's default when it can't detect a framework. This is the #1 cause of missing API routes in monorepos.

---

🔧 Troubleshooting

If API routes STILL don't deploy after all 4 steps:

1. Check Build Logs:

   • Does it say "Detected Next.js"?
   • Does it list "route (app) /api/*"?
   • Does it show @vercel/next builder?

2. Check package.json location:

   ✓ Should exist: apps/web/package.json
   ✗ Should NOT be at root ONLY
   

3. Check next.config.ts location:

   ✓ Should exist: apps/web/next.config.ts
   

4. Verify pnpm workspace:

   # Should show @tpmjs/web
   pnpm list --depth 0 --filter @tpmjs/web
   

5. Test local build with Vercel CLI:

   cd apps/web
   vercel build --debug
   

   Look for "Framework: nextjs" in output.

---

📞 When to Contact Vercel Support

If after completing all 4 steps:

• Build logs show "Detected Next.js"
• Build logs show "route (app) /api/*"
• BUT vercel inspect still doesn't list API functions

Then you have a Vercel platform bug. Contact support with:

• This checklist
• Build logs
• vercel inspect output
• Link to API_ROUTES_TIMEOUT_INVESTIGATION.md

---

🎯 Quick Win Test

Don't want to change production settings yet?

1. Create a NEW Vercel project
2. Import the SAME repo
3. Set Root Directory to apps/web
4. Set Framework Preset to "Next.js"
5. Deploy

If API routes work in the new project → confirms the fix If API routes still fail → deeper issue (contact support)

---

✨ Post-Fix Cleanup

Once API routes are working:

Optional: Re-add www redirect

Now that API routes work, you can safely add the www redirect back:

Option A - Vercel Project Settings: Vercel Dashboard → Domains → tpmjs.com → Redirect www to apex

Option B - Next.js config:

// apps/web/next.config.ts
async redirects() {
  return [
    {
      source: '/:path((?!api).*)*', // Exclude /api/*
      has: [{ type: 'host', value: 'www.tpmjs.com' }],
      destination: 'https://tpmjs.com/:path*',
      permanent: true,
    },
  ];
}

Option C - vercel.json (not recommended): Only use if you understand the implications.

Optional: Remove maxDuration exports

The export const maxDuration = 60; in your route files isn't needed unless you actually need longer timeouts. Default is 10s (Hobby) or 15s (Pro).

---

📊 Summary

Issue	Root Cause	Fix
API routes timeout	Vercel doesn't detect Next.js	Set Framework Preset to "Next.js"
No λ functions in build	Wrong Root Directory	Set to apps/web exactly
"Redirecting..." on API calls	Domain on two projects	Remove from old project
Build doesn't find API routes	Custom build commands break detection	Clear custom commands

Time to fix: 5 minutes (just changing dashboard settings) Deployments needed: 1 (changes take effect on next deploy) Code changes needed: 0 (this is pure configuration)

---

🎉 When It Works

You'll know it's fixed when:

$ curl https://tpmjs.com/api/health
{"status":"ok","timestamp":"2025-11-28T...","env":{"hasDatabase":true,"nodeEnv":"production"}}

$ curl https://tpmjs.com/api/tools
{"data":[...],"pagination":{...}}

And vercel inspect <url> shows:

Builds
  ├── λ api/health
  ├── λ api/tools
  ├── λ api/stats
  ... (ALL your API routes)

That's it. No code changes. Just fix the Vercel project configuration.