Use when installing or wiring Tailwind CSS into a Next.js project, for either the App Router or the Pages Router, on Tailwind v3 or v4, and when hooking next/font/google families into the Tailwind theme so utilities like font-sans resolve to the loaded family. Prevents the four most common Next-js install traps: importing globals.css in the wrong file for the active router, forgetting the @tailwindcss/postcss plugin under v4, breaking the v3 content glob on catch-all route folders named [...slug], and pasting font CSS variables into next/font/local without declaring them inside @theme inline so they never become utilities. Covers v4 App Router with @import tailwindcss, v4 Pages Router, v3 App Router with @tailwind directives, v3 Pages Router, next/font wiring via className on html plus @theme inline { --font-sans: var(--font-inter) }, why React Server Components have zero runtime cost from Tailwind, and the Turbopack arbitrary-value miss workaround for Next 16 plus v4 from tailwindlabs/tailwindcss issue 19825
Use when installing or wiring Tailwind CSS into a Next.js project, for either the App Router or the Pages Router, on Tailwind v3 or v4, and when hooking next/font/google families into the Tailwind theme so utilities like font-sans resolve to the loaded family. Prevents the four most common Next-js install traps: importing globals.css in the wrong file for the active router, forgetting the @tailwindcss/postcss plugin under v4, breaking the v3 content glob on catch-all route folders named [...slug], and pasting font CSS variables into next/font/local without declaring them inside @theme inline so they never become utilities. Covers v4 App Router with @import tailwindcss, v4 Pages Router, v3 App Router with @tailwind directives, v3 Pages Router, next/font wiring via className on html plus @theme inline { --font-sans: var(--font-inter) }, why React Server Components have zero runtime cost from Tailwind, and the Turbopack arbitrary-value miss workaround for Next 16 plus v4 from tailwindlabs/tailwindcss issue 19825. Keywords: tailwind nextjs, tailwind next-js, install tailwind next, next app router tailwind, next pages router tailwind, app/globals-css, pages/_app-tsx, @tailwindcss/postcss, postcss-config-mjs, tailwind v4 next, tailwind v3 next, @import tailwindcss next, @tailwind directives next, tailwind init -p next, next/font google tailwind, next/font local tailwind, --font-inter @theme inline, font-sans next/font, RSC tailwind, server components tailwind, no runtime cost styling, turbopack arbitrary value miss, aspect-[12/5] missing turbopack, z-[100] missing, next 16 tailwind v4 issue 19825, catch-all route [...slug] glob, @source './[[]**[]]', how do I add tailwind to next, my tailwind classes are not applying in nextjs, blank styles next, why doesn't dark mode work next, getting started tailwind next.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
Tailwind CSS in Next.js : Install and Wire-up
Covers every supported combination of Tailwind version (v3.4 vs v4.0+) and
Next.js router (App Router vs Pages Router), plus next/font integration
and the documented Turbopack quirk.
That is the complete v4 + App Router install. No tailwind.config.js, no
@tailwind directives, no autoprefixer, no postcss-import. The
@tailwindcss/postcss plugin runs the Oxide engine which bundles all
three.
Same install, same tailwind.config.js, same postcss.config.js. The CSS
file lives at styles/globals.css (same three @tailwind directives),
imported once in pages/_app.tsx :
next/font emits a CSS variable that you opt into by applying a className.
Tailwind reads that variable as a token via @theme (v4) or
fontFamily.extend (v3).
v4 pattern
app/layout.tsx :
import { Inter } from"next/font/google";
import"./globals.css";
const inter = Inter({
subsets: ["latin"],
variable: "--font-inter",
});
exportdefaultfunctionRootLayout({ children }: { children: React.ReactNode }) {
return (
<htmllang="en"className={inter.variable}><bodyclassName="font-sans">{children}</body></html>
);
}
ALWAYS use @theme inline { ... } (not bare @theme { ... }) when the
token value contains a var(...) reference to another CSS variable that
exists at runtime. Bare @theme resolves the variable at build time and
emits the resolved literal, which is empty before next/font runs and
strips the family.
v3 pattern
pages/_app.tsx (or app/layout.tsx) wires the className the same way.
The config file declares the family :
Tailwind is a build-time compiler. It scans source files for class
tokens, generates a single static CSS bundle, and injects that bundle via
the same <link rel="stylesheet"> Next.js uses for every other CSS
import. There is no client runtime, no Server Component restriction, no
"use client" boundary needed for styling. RSC, Client Components, and
Server Actions all consume the same CSS.
Consequences :
NEVER move a Server Component to Client just to use Tailwind classes.
ALWAYS apply Tailwind classes directly on RSC output ; no wrapper.
Bundle size scales with the number of utilities used, not with the
number of components. Adding a hundred RSC components that share the
same utilities adds zero CSS bytes.
Turbopack Arbitrary-Value Miss (Issue 19825)
Affects Next.js 16.1.6 + Tailwind v4.2.1 + next dev --turbo (and
next dev once Turbopack becomes the default). Classes with arbitrary
square-bracket values render in the DOM but the corresponding CSS rule
is missing from the injected stylesheet.
Reproduced tokens : aspect-[12/5], z-[100], h-[80vh]. The same
classes compile correctly under webpack (next dev without --turbo).
Safelist the exact token via @source inline so the scanner is
forced to emit the rule regardless of Turbopack's incremental scan :
@source inline("aspect-[12/5] z-[100] h-[80vh]");
Disable Turbopack for the affected build : remove --turbo from
next dev until the upstream fix lands.
NEVER ship aspect-[12/5] style arbitrary values to a Turbopack
production build without first verifying the rule appears in
.next/static/css. The DOM showing the class is not proof the CSS
exists.
Catch-All Route Glob Trap (Tailwind v3)
The default v3 content glob ./app/**/*.{js,ts,jsx,tsx,mdx} treats
square brackets as a character class. Files inside a folder named
[...slug] or [id] are silently excluded from the scan. Symptom :
classes on dynamic-route pages produce no CSS.
Fix (v3) : add a second content entry that escapes the brackets, or
list the catch-all folder explicitly :
