opencode-skill/skills/website-creator/payload-nextjs-turbopack-fix/SKILL.md

name, description, tags, category

name	description	tags	category
payload-nextjs-turbopack-fix	Fix Payload CMS white screen / module load errors when using Next.js 16 with Turbopack	payload nextjs turbopack troubleshooting white-screen	software-development

Payload CMS + Next.js 16 Turbopack White Screen Fix

Symptom

Payload CMS admin shows white screen or "initializing" forever. Console/network tab shows:

Error: Failed to load external module @payloadcms/db-mongodb-XXXXXXXXXXXX
ResolveMessage: Cannot find module '@payloadcms/db-mongodb-XXXXXXXXXXXX'

Or server returns HTTP 500 on /admin/create-first-user or /admin.

Root Cause

Next.js 16 defaults to Turbopack in dev mode. Payload CMS 3.x (specifically @payloadcms/db-mongodb) is NOT compatible with Turbopack's module resolution — it uses Webpack-specific module IDs that Turbopack can't resolve.

Fix Steps

Step 1: Verify MongoDB is running

ss -tlnp | grep -E '27019|27017'
pgrep -a mongo

MongoDB must be running on the expected port. Check .env for MONGODB_URL.

Step 2: Remove Next.js 16-only experimental options from next.config.ts

When downgrading from Next 16 → 15, remove any experimental.turbo config that was added for Next 16. In Next.js 15 this option doesn't exist and generates a warning:

// WRONG in Next.js 15 — 'turbo' is not a known ExperimentalConfig key
experimental: {
  turbo: undefined,
},

// CORRECT — remove experimental.turbo entirely for Next.js 15

Step 3: Downgrade Next.js to 15.x (15.5.x)

cd /path/to/moreminimore-next
bun add next@15.5.15 react@19.0.0 react-dom@19.0.0

Next.js 15 uses Webpack by default in dev mode, which is fully compatible with Payload CMS.

Why not just disable Turbopack?

• Next.js 16 has NO --no-turbo flag (error: unknown option)
• NEXT_TURBOPACK=0 env var does NOT disable Turbopack in Next 16 (still starts with Turbopack)
• experimental.turbo: undefined in next.config.ts does NOT disable it in Next 16
• Downgrade to Next.js 15.x is the only viable option

Step 3: Verify version

cat node_modules/next/package.json | grep '"version"'

Should show 15.5.x (not 16.x).

Step 4: Clear cache and restart

pkill -9 -f next 2>/dev/null
rm -rf .next
bun run dev

Step 5: Verify admin loads

Navigate to http://localhost:3000/admin — should show Payload login screen.

Compatibility Matrix

Next.js	Bundler	Payload CMS	Status
16.x	Turbopack (default)	3.x	BROKEN
16.x	Webpack (flag)	3.x	No flag available
15.5.x	Webpack (default)	3.x	WORKS
14.x	Webpack	3.x	WORKS

Additional Dev Server Issues (Lessons Learned)

Server crashes after "Ready in Xms"

Even with Next.js 15.5.15, the dev server may crash silently right after "Ready" message. Two known causes:

1. output: 'standalone' in next.config.ts

This causes Next.js to crash immediately after starting in dev mode. Remove it:

// WRONG — causes crash after "Ready" in dev mode
const nextConfig: NextConfig = {
  output: 'standalone',  // REMOVE THIS
  ...
}

// CORRECT — no output option in dev
const nextConfig: NextConfig = {
  // (no output key)
  ...
}

2. NEXT_TURBOPACK=0 in dev script

This env var can cause issues even on Next.js 15. Remove it:

// WRONG
"dev": "cross-env NODE_OPTIONS=--no-deprecation NEXT_TURBOPACK=0 next dev"

// CORRECT
"dev": "cross-env NODE_OPTIONS=--no-deprecation next dev"

Restart with clean .next cache after making changes:

pkill -9 -f next; sleep 1
rm -rf .next
bun run dev

Server starts but port 3000 shows nothing / 404

If ss -tlnp | grep 3000 shows the port is listening but the site returns 404:

1. Check if there's a compiled .next cache from a previous version — always rm -rf .next before restarting
2. Verify MongoDB is running: pgrep -a mongo
3. Check server logs: cat /tmp/moredev.log

Blog Posts Migration (Astro MD → Payload CMS)

Script location: src/scripts/migrate-posts.ts

Key approach:

• Use absolute paths for configPath and blogDir (avoid relative path resolution issues with ESM)
• Use dynamic imports for Payload config to avoid bundling issues
• Store content as plain text (strip markdown syntax with regex replacements)
• Check for existing posts by slug before creating (idempotent)

cd /home/kunthawat/moreminimore-next
npx tsx src/scripts/migrate-posts.ts

What to check if still broken

1. sharp module: If you see Failed to load external module sharp-XXX, check node_modules/sharp exists:

   ls node_modules/sharp
   

   If missing: bun add sharp

2. MongoDB connection: Ensure MONGODB_URL in .env matches running mongod port

3. Port conflict: If port 3000 is in use:

   pkill -9 -f next; pkill -9 -f bun
   ss -tlnp | grep 3000
   

4. Dev server process shows "Killed" but server is still running: The bun run dev foreground process may get killed by the shell even when the Next.js server starts successfully. Always check port 3000 directly:

   ss -tlnp | grep 3000
   pgrep -a next-server
   

   If port 3000 is listening, the server IS running — ignore the "Killed" message.

5. TypeScript lint errors from node_modules: The next lint output shows many TS errors from node_modules/ (e.g., @types/react, next/dist/...). These are non-blocking noise — they don't prevent the dev server from running or the admin from loading. Ignore them.

Key Takeaway

Next.js 16 + Turbopack is incompatible with Payload CMS 3.x database adapters. Always downgrade to Next.js 15.5.x when using Payload with MongoDB adapter.