Next.js App Router and Tailwind v4

The App Router and Tailwind v4 both punish habits carried over from their previous versions, and both do it quietly: the page renders, the class is ignored, nothing errors. This skill is the set of rules that catch that.

When to use this

Writing or reviewing anything in a Next.js 14+ App Router project: pages, layouts, components, route handlers, metadata, Tailwind classes.

Server components are the default. Keep them that way.

'use client' is not a fix for a build error. Every time you add it, you move the component and its whole import subtree into the browser bundle.

Add it only for: useState/useEffect/useRef, event handlers, browser APIs, or a library that needs them. Anything else stays on the server.

The pattern that keeps the boundary small — a server page fetching data, handing a serialised prop to a thin client leaf:

// app/thing/[slug]/page.tsx  — server, no directive
import { getThing } from '@/lib/things';
import ThingChart from '@/components/ThingChart'; // 'use client' lives THERE

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;              // params is a Promise in Next 15+
  const thing = await getThing(slug);
  if (!thing) notFound();
  return <ThingChart points={thing.points} />;
}

Push 'use client' down to the leaf that needs it, never up to the page.

Props crossing the boundary must be serialisable. Functions, class instances, Date, Map, Set and React components do not cross. Pass a slug and resolve the component from a client-side registry on the other side.

Data fetching

• fetch in a server component is cached and deduped. Two components fetching the same URL in one render make one request.
• export const dynamic = 'force-static' on a route handler that reads only local content.
• export const revalidate = 3600 beats a hand-rolled cache.
• Never fetch your own API route from a server component. It is an HTTP round trip to yourself. Call the function the route handler calls.
• Never fetch same-server data from a client component with a loading spinner. Render it on the server; the data is already there. A skeleton for data the server could have inlined is a self-inflicted layout shift.

Metadata

export async function generateMetadata({ params }): Promise<Metadata> {
  const { slug } = await params;
  const thing = await getThing(slug);
  if (!thing) return {};
  return {
    title: thing.seoTitle,
    description: thing.seoDescription,
    alternates: { canonical: `https://example.com/thing/${slug}` },
    openGraph: { title: thing.seoTitle, images: [`/og/thing/${slug}.png`] },
  };
}

export function generateStaticParams() {
  return allSlugs.map((slug) => ({ slug }));
}

generateMetadata and the page body both run; shared work is deduped by the fetch cache, so do not thread data between them manually.

Tailwind v4, and what changed

Configuration moved into CSS. @theme in your stylesheet, not theme.extend in a config file. A v3 config still works through the compat layer, but new tokens belong in CSS.

Opacity modifiers now compile to color-mix. This is the good news: bg-[var(--x)]/10 works on an arbitrary CSS variable, which it could not in v3. Design tokens as CSS variables plus opacity modifiers is now the idiomatic pattern.

transform utilities are standalone. In v3, scale-105 implied transform. In v4 scale, translate and rotate are independent properties. So:

<!-- broken in v4: transitions nothing -->
<div class="transition-transform hover:scale-105">

<!-- correct -->
<div class="transition-[scale] hover:scale-105">
<div class="transition-[scale,translate] hover:scale-105 hover:-translate-y-1">

This is the single most common silent v4 breakage: the hover still applies, it just snaps instead of animating.

Class names must be statically visible. Tailwind scans source text. `bg-${c}-500` generates nothing. Write full class strings and pick between them:

const TONE = {
  ok:   'bg-green-500/10 text-green-600',
  warn: 'bg-amber-500/10 text-amber-600',
} as const;

Default border colour changed from gray-200 to currentColor. A bare border inherits text colour now. Always name the colour.

Review checklist

• Is 'use client' on the smallest component that needs it?
• Do all boundary props serialise?
• Is params awaited?
• Does every dynamic route have generateStaticParams where the set is known?
• Any interpolated Tailwind class names?
• Any transition-transform paired with a v4 standalone transform utility?
• Any client-side fetch of data the server already had?
• Any border without an explicit colour?