nextjs-expert

Next.js Expert Skill

Version: 2.1 (Next.js 16+ with MCP Integration) Author: FrankX AI Systems Last Updated: 2026-05-13

Platform baseline (Next.js 16 + Vercel, May 2026)

• Next.js: 16.x (Turbopack is the default build/dev engine; webpack is opt-in only)
• React: 18.3 stable on FrankX; React 19 RSC patterns supported
• Node: 24 LTS by default on Vercel
• Functions: Vercel Fluid Compute (concurrency-aware Node functions) — not legacy Edge/Serverless. Default maxDuration = 300s for Hobby/Pro.
• Config files: next.config.ts (or .mjs) for framework. Platform config: vercel.ts is the recommended way (typed VercelConfig, env-aware logic, programmatic functions per vercel:knowledge-update 2026-02-27). vercel.json still works for simple cases. FrankX currently uses vercel.json + next.config.mjs — migrate to vercel.ts when you need typed config, dynamic logic, or env-var access at config time.
• Caching: "Cache Components" (formerly PPR) is the forward-looking primitive — cacheComponents: true at top level of next.config, NOT under experimental.

Next.js 16 gotchas (production-critical)

These bite real builds. Memorize them.

1. Dynamic route params is now a Promise — always

Every dynamic route page, layout, route handler, and generateMetadata receives params as Promise<{...}>. Synchronous access (the Next 15 pattern) builds fine but 404s every request in production.

// BROKEN in Next 16 (compiles, silently 404s)
export default function Page({ params }: { params: { slug: string } }) {
  return <div>{params.slug}</div>
}

// CORRECT — async + await
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <div>{slug}</div>
}

Same rule for generateMetadata, generateStaticParams, route handlers, and searchParams (also a Promise).

2. app/<name>.ts collides with app/<name>/page.tsx under Turbopack