Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra is fully compatible with Tailwind CSS v4, the modern utility-first CSS framework. Because nextra-theme-docs ships its own Tailwind-generated classes, you can safely add Tailwind v4 to your project without worrying about conflicts — both sets of styles coexist cleanly through standard CSS cascade rules and @layer ordering.

​
Installation

1
Install Tailwind CSS v4 dependencies
2
Install the required Tailwind CSS v4 packages:
3
npm
npm install tailwindcss @tailwindcss/postcss
pnpm
pnpm add tailwindcss @tailwindcss/postcss
yarn
yarn add tailwindcss @tailwindcss/postcss
4
Tailwind CSS v4 no longer requires a tailwind.config.js file. Configuration is done entirely through CSS using directives like @theme and @utility.
5
Configure PostCSS
6
Create or update postcss.config.mjs in your project root to use the Tailwind v4 PostCSS plugin:
7
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}
8
Create your globals.css file
9
Import Tailwind into your globals.css file using the new v4 CSS import syntax. You can also import your Nextra theme styles in the same file:
10
@import "tailwindcss";

/* Import Nextra theme styles */
@import "nextra-theme-docs/style.css";

/* Required for Nextra dark mode variant support */
@variant dark (&:where(.dark *));
11
Import styles in your root layout
12
Apply the styles globally by importing globals.css in your root layout file:
13
import '../path/to/your/globals.css'

export default async function RootLayout({ children }) {
  // ... Your layout logic here
}

​
Custom Utilities with @utility

Tailwind CSS v4 introduces the @utility directive, which lets you define custom utility classes that integrate natively with Tailwind’s engine — including variant support, arbitrary values, and JIT compilation.
globals.css
@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
}

@utility tab-* {
  tab-size: --value(integer);
}
These custom utilities behave exactly like built-in Tailwind classes. They respond to variants (e.g., hover:content-auto, lg:tab-4) and are only included in the output if actually used.
Use @utility instead of @layer utilities in Tailwind v4. The old approach still works but @utility offers better integration with the new engine, including support for functional utilities using --value().

​
Cascade Layers and nextra-theme-docs

nextra-theme-docs uses Tailwind CSS v4 internally and outputs styles within CSS @layer declarations. Understanding how cascade layers interact helps you override theme styles predictably.

​
Default style import

By default, when you import nextra-theme-docs/style.css, its styles are placed into Tailwind’s standard layers. Your custom styles added outside a layer always win over layered styles:
globals.css
@import "tailwindcss";
@import "nextra-theme-docs/style.css";

/* This always overrides nextra-theme-docs because it's outside any @layer */
.nextra-nav-container {
  background-color: #1a1a2e;
}

​
Using @layer for explicit ordering

When you need fine-grained control, declare explicit layer ordering before any imports. Layers declared later in the @layer statement have higher priority:
globals.css
@import "tailwindcss";

/* Declare layers: nextra styles come first, your overrides come last */
@layer nextra-theme, base, components, utilities, overrides;

@import "nextra-theme-docs/style.css" layer(nextra-theme);

@layer overrides {
  /* These styles win over nextra-theme-docs regardless of specificity */
  :root {
    --nextra-primary-hue: 212deg;
  }
}

​
CSS layer isolation with style-prefixed.css

nextra-theme-docs also ships a style-prefixed.css variant. Whereas style.css uses the standard Tailwind v4 layer names (@layer base and @layer utilities), style-prefixed.css renames those layers to v4-base and v4-utilities. This prevents accidental merging with your own base or utilities layers when both sets of styles are loaded in the same cascade:
globals.css
@import "tailwindcss";

/* Use the prefixed-layer variant to avoid layer name collisions */
@import "nextra-theme-docs/style-prefixed.css";
When using style-prefixed.css, your own @layer base and @layer utilities rules will no longer share a layer with the theme’s styles. Test your overrides thoroughly when switching between the standard and prefixed style imports.

​
Coexistence with nextra-theme-docs

A common concern is whether adding Tailwind CSS to your project will conflict with the Tailwind classes already used by nextra-theme-docs. The short answer is: they do not conflict. nextra-theme-docs ships pre-compiled CSS — it does not re-run the Tailwind compiler at your project’s build time. Your project’s Tailwind instance only scans and processes files you configure (your app/ directory, components, etc.). The two sets of generated classes live independently in the final CSS output.
If you see unexpected style conflicts, check your @layer ordering. Styles outside any @layer always take precedence over layered styles, so moving your overrides outside a layer is often the simplest fix.

​
Full example

Here is a complete setup combining Tailwind CSS v4 with nextra-theme-docs: 
@import "tailwindcss";
@import "nextra-theme-docs/style.css";

@variant dark (&:where(.dark *));

@utility prose-tight {
  line-height: 1.4;
}

@layer base {
  :root {
    --nextra-primary-hue: 220deg;
    --nextra-primary-saturation: 80%;
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us