docs: Create tailwind guide (#78908)

delbaoliveira · eps1lon · commit ffa5278b3983 · 2025-05-07T20:32:46.000+02:00
Closes: https://linear.app/vercel/issue/DOC-4643/tailwind Redirects: vercel/front#45246
diff --git a/docs/01-app/01-getting-started/05-css.mdx b/docs/01-app/01-getting-started/05-css.mdx
@@ -6,6 +6,7 @@ related:
   title: Next Steps
   description: Learn more about the features mentioned in this page.
   links:
+    - app/guides/tailwind-css
     - app/guides/sass
     - app/guides/css-in-js
 ---
@@ -14,10 +15,10 @@ Next.js provides several ways to use CSS in your application, including:
 
 - [CSS Modules](#css-modules)
 - [Global CSS](#global-css)
-- [Tailwind CSS](#tailwind-css)
+- [External Stylesheets](#external-stylesheets)
+- [Tailwind CSS](/docs/app/guides/tailwind-css)
 - [Sass](/docs/app/guides/sass)
 - [CSS-in-JS](/docs/app/guides/css-in-js)
-- [External Stylesheets](#external-stylesheets)
 
 ## CSS Modules
 
@@ -93,96 +94,6 @@ export default function RootLayout({ children }) {
 
 > **Good to know:** Global styles can be imported into any layout, page, or component inside the `app` directory. However, since Next.js uses React's built-in support for stylesheets to integrate with Suspense, this currently does not remove stylesheets as you navigate between routes which can lead to conflicts. We recommend using global styles for _truly_ global CSS, and [CSS Modules](#css-modules) for scoped CSS.
 
-## Tailwind CSS
-
-[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework that integrates seamlessly with Next.js.
-
-### Installing Tailwind
-
-To start using Tailwind, install the necessary Tailwind CSS packages:
-
-```bash filename="Terminal"
-npm install tailwindcss @tailwindcss/postcss postcss
-```
-
-### Configuring Tailwind
-
-Create a `postcss.config.mjs` file in the root of your project and add the `@tailwindcss/postcss` plugin to your PostCSS configuration:
-
-```js filename="postcss.config.mjs" highlight={4}
-/** @type {import('tailwindcss').Config} */
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-}
-```
-
-### Using Tailwind
-
-Add the [Tailwind directives](https://tailwindcss.com/docs/functions-and-directives#directives) to your [Global Stylesheet](#global-css):
-
-```css filename="app/globals.css"
-@import 'tailwindcss';
-```
-
-Then, import the styles in the [root layout](/docs/app/api-reference/file-conventions/layout#root-layouts):
-
-```tsx filename="app/layout.tsx" switcher
-import type { Metadata } from 'next'
-// These styles apply to every route in the application
-import './globals.css'
-
-export const metadata: Metadata = {
-  title: 'Create Next App',
-  description: 'Generated by create next app',
-}
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-```jsx filename="app/layout.js" switcher
-// These styles apply to every route in the application
-import './globals.css'
-
-export const metadata = {
-  title: 'Create Next App',
-  description: 'Generated by create next app',
-}
-
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  )
-}
-```
-
-You can then start writing Tailwind's utility classes in your application.
-
-```tsx filename="app/page.tsx" switcher
-export default function Page() {
-  return <h1 className="text-3xl font-bold underline">Hello, Next.js!</h1>
-}
-```
-
-```jsx filename="app/page.js" switcher
-export default function Page() {
-  return <h1 className="text-3xl font-bold underline">Hello, Next.js!</h1>
-}
-```
-
 ## External stylesheets
 
 Stylesheets published by external packages can be imported anywhere in the `app` directory, including colocated components:
diff --git a/docs/01-app/02-guides/css-in-js.mdx b/docs/01-app/02-guides/css-in-js.mdx
@@ -32,7 +32,7 @@ The following are currently working on support:
 
 > **Good to know**: We're testing out different CSS-in-JS libraries and we'll be adding more examples for libraries that support React 18 features and/or the `app` directory.
 
-If you want to style Server Components, we recommend using [CSS Modules](/docs/app/building-your-application/styling/css) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css).
+If you want to style Server Components, we recommend using [CSS Modules](/docs/app/building-your-application/styling/css) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/guides/tailwind-css).
 
 ## Configuring CSS-in-JS in `app`
 
diff --git a/docs/01-app/02-guides/migrating/app-router-migration.mdx b/docs/01-app/02-guides/migrating/app-router-migration.mdx
@@ -887,7 +887,7 @@ If you are also migrating to Next.js from a Single-Page Application (SPA) at the
 In the `pages` directory, global stylesheets are restricted to only `pages/_app.js`. With the `app` directory, this restriction has been lifted. Global styles can be added to any layout, page, or component.
 
 - [CSS Modules](/docs/app/building-your-application/styling/css#css-modules)
-- [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css)
+- [Tailwind CSS](/docs/app/guides/tailwind-css)
 - [Global Styles](/docs/app/building-your-application/styling/css#global-styles)
 - [CSS-in-JS](/docs/app/guides/css-in-js)
 - [External Stylesheets](/docs/app/building-your-application/styling/css#external-stylesheets)
@@ -921,7 +921,7 @@ export default function RootLayout({ children }) {
 }
 ```
 
-Learn more about [styling with Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css)
+Learn more about [styling with Tailwind CSS](/docs/app/guides/tailwind-css)
 
 ## Using App Router together with Pages Router
 
diff --git a/docs/01-app/02-guides/migrating/from-create-react-app.mdx b/docs/01-app/02-guides/migrating/from-create-react-app.mdx
@@ -300,7 +300,7 @@ export default function RootLayout({
 }
 ```
 
-If you’re using Tailwind CSS, see our [installation docs](/docs/app/building-your-application/styling/tailwind-css).
+If you’re using Tailwind CSS, see our [installation docs](/docs/app/guides/tailwind-css).
 
 ### Step 6: Create the Entrypoint Page
 
diff --git a/docs/01-app/02-guides/tailwind-css.mdx b/docs/01-app/02-guides/tailwind-css.mdx
@@ -1,11 +1,12 @@
 ---
-title: Tailwind CSS
+title: How to install Tailwind CSS in your Next.js application
+nav_title: Tailwind CSS
 description: Style your Next.js Application using Tailwind CSS.
 ---
 
 {/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
 
-[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework that is fully compatible with Next.js.
+[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework that is fully compatible with Next.js. This guide will walk you through how to install Tailwind CSS in your Next.js application.
 
 ## Installing Tailwind
 
@@ -15,6 +16,8 @@ Install the necessary Tailwind CSS packages:
 npm install -D tailwindcss @tailwindcss/postcss postcss
 ```
 
+> **Good to know**: If you're using the `create-next-app` CLI to create your project, Next.js will prompt if you'd like to install Tailwind and automatically configure the project.
+
 ## Configuring Tailwind
 
 Create a `postcss.config.mjs` file in the root of your project and add the `@tailwindcss/postcss` plugin to your PostCSS configuration:
diff --git a/docs/01-app/03-building-your-application/05-styling/01-css.mdx b/docs/01-app/03-building-your-application/05-styling/01-css.mdx
@@ -348,7 +348,7 @@ To maintain a predictable order, we recommend the following:
 - Prefer CSS Modules over global styles.
   - Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`.
 - Extract shared styles into a separate shared component.
-- If using [Tailwind](/docs/app/building-your-application/styling/tailwind-css), import the stylesheet at the top of the file, preferably in the [Root Layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required).
+- If using [Tailwind](/docs/app/guides/tailwind-css), import the stylesheet at the top of the file, preferably in the [Root Layout](/docs/app/building-your-application/routing/layouts-and-templates#root-layout-required).
 - Turn off any linters/formatters (e.g., ESLint's [`sort-import`](https://eslint.org/docs/latest/rules/sort-imports)) that automatically sort your imports. This can inadvertently affect your CSS since CSS import order _matters_.
 
 > **Good to know:**
diff --git a/docs/01-app/05-api-reference/02-components/font.mdx b/docs/01-app/05-api-reference/02-components/font.mdx
@@ -827,7 +827,7 @@ export default function MyApp({ Component, pageProps }) {
 
 </PagesOnly>
 
-Finally, add the CSS variable to your [Tailwind CSS config](/docs/app/building-your-application/styling/tailwind-css#configuring-tailwind):
+Finally, add the CSS variable to your [Tailwind CSS config](/docs/app/guides/tailwind-css#configuring-tailwind):
 
 ### Tailwind CSS v4
 
diff --git a/docs/02-pages/01-getting-started/06-css.mdx b/docs/02-pages/01-getting-started/06-css.mdx
@@ -0,0 +1,15 @@
+---
+title: How to use CSS in your application
+nav_title: CSS
+description: Learn about the different ways to add CSS to your application, including CSS Modules, Global CSS, Tailwind CSS, and more.
+related:
+  title: Next Steps
+  description: Learn more about the features mentioned in this page.
+  links:
+    - pages/guides/tailwind-css
+    - pages/guides/sass
+    - pages/guides/css-in-js
+source: app/getting-started/css
+---
+
+{/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
diff --git a/docs/02-pages/02-guides/tailwind-css.mdx b/docs/02-pages/02-guides/tailwind-css.mdx
@@ -1,7 +1,7 @@
 ---
 title: Tailwind CSS
 description: Style your Next.js Application using Tailwind CSS.
-source: app/building-your-application/styling/tailwind-css
+source: app/guides/tailwind-css
 ---
 
 {/* DO NOT EDIT. The content of this doc is generated from the source above. To edit the content of this page, navigate to the source page in your editor. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}

Original file line number	Diff line number	Diff line change
`@@ -300,7 +300,7 @@ export default function RootLayout({`
`300`	`300`	`}`
`301`	`301`	```
`302`	`302`
`303`		`-If you’re using Tailwind CSS, see our [installation docs](/docs/app/building-your-application/styling/tailwind-css).`
	`303`	`+If you’re using Tailwind CSS, see our [installation docs](/docs/app/guides/tailwind-css).`
`304`	`304`
`305`	`305`	`### Step 6: Create the Entrypoint Page`
`306`	`306`