Unverified Commit a38db346 authored by Joseph's avatar Joseph Committed by GitHub

Docs: Add more info about TW and TW 3 option (#82203)

Closes: https://linear.app/vercel/issue/DOC-4862/tailwind-css-modules

---------
Co-authored-by: 's avatarRich Haines <hello@richardhaines.dev>
parent eb756a63
---
title: CSS
description: Learn about the different ways to add CSS to your application, including CSS Modules, Global CSS, Tailwind CSS, and more.
description: Learn about the different ways to add CSS to your application, including Tailwind CSS, CSS Modules, Global CSS, and more.
related:
title: Next Steps
description: Learn more about the alternatives ways you can use CSS in your application.
links:
- app/guides/tailwind-css
- app/guides/tailwind-v3-css
- app/guides/sass
- app/guides/css-in-js
---
Next.js provides several ways to style your application using CSS, including:
- [Tailwind CSS](#tailwind-css)
- [CSS Modules](#css-modules)
- [Global CSS](#global-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)
## Tailwind CSS
[Tailwind CSS](https://tailwindcss.com/) is a utility-first CSS framework that provides low-level utility classes to build custom designs.
<AppOnly>
Install Tailwind CSS:
```bash package="pnpm"
pnpm add -D tailwindcss @tailwindcss/postcss
```
```bash package="npm"
npm install -D tailwindcss @tailwindcss/postcss
```
```bash package="yarn"
yarn add -D tailwindcss @tailwindcss/postcss
```
```bash package="bun"
bun add -D tailwindcss @tailwindcss/postcss
```
Add the PostCSS plugin to your `postcss.config.mjs` file:
```js filename="postcss.config.mjs"
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}
```
Import Tailwind in your global CSS file:
```css filename="app/globals.css"
@import 'tailwindcss';
```
Import the CSS file in your root layout:
```tsx filename="app/layout.tsx" switcher
import './globals.css'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
```
```jsx filename="app/layout.js" switcher
import './globals.css'
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
```
Now you can start using Tailwind's utility classes in your application:
```tsx filename="app/page.tsx" switcher
export default function Page() {
return (
<main className="flex min-h-screen flex-col items-center justify-between p-24">
<h1 className="text-4xl font-bold">Welcome to Next.js!</h1>
</main>
)
}
```
```jsx filename="app/page.js" switcher
export default function Page() {
return (
<main className="flex min-h-screen flex-col items-center justify-between p-24">
<h1 className="text-4xl font-bold">Welcome to Next.js!</h1>
</main>
)
}
```
</AppOnly>
<PagesOnly>
Install Tailwind CSS:
```bash package="pnpm"
pnpm add -D tailwindcss @tailwindcss/postcss
```
```bash package="npm"
npm install -D tailwindcss @tailwindcss/postcss
```
```bash package="yarn"
yarn add -D tailwindcss @tailwindcss/postcss
```
```bash package="bun"
bun add -D tailwindcss @tailwindcss/postcss
```
Add the PostCSS plugin to your `postcss.config.mjs` file:
```js filename="postcss.config.mjs"
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}
```
Import Tailwind in your global CSS file:
```css filename="styles/globals.css"
@import 'tailwindcss';
```
Import the CSS file in your `pages/_app.js` file:
```jsx filename="pages/_app.js"
import '@/styles/globals.css'
export default function MyApp({ Component, pageProps }) {
return <Component {...pageProps} />
}
```
Now you can start using Tailwind's utility classes in your application:
```tsx filename="pages/index.tsx" switcher
export default function Home() {
return (
<main className="flex min-h-screen flex-col items-center justify-between p-24">
<h1 className="text-4xl font-bold">Welcome to Next.js!</h1>
</main>
)
}
```
```jsx filename="pages/index.js" switcher
export default function Home() {
return (
<main className="flex min-h-screen flex-col items-center justify-between p-24">
<h1 className="text-4xl font-bold">Welcome to Next.js!</h1>
</main>
)
}
```
</PagesOnly>
> **Good to know:** If you need broader browser support for very old browsers, see the [Tailwind CSS v3 setup instructions](/docs/app/guides/tailwind-v3-css).
## CSS Modules
CSS Modules locally scope CSS by generating unique class names. This allows you to use the same class in different files without worrying about naming collisions.
......@@ -125,7 +291,7 @@ 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.
> **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 (like Tailwind's base styles), [Tailwind CSS](#tailwind-css) for component styling, and [CSS Modules](#css-modules) for custom scoped CSS when needed.
</AppOnly>
......@@ -277,7 +443,8 @@ To keep CSS ordering predictable:
- Try to contain CSS imports to a single JavaScript or TypeScript entry file
- Import global styles and Tailwind stylesheets in the root of your application.
- Use CSS Modules instead of global styles for nested components.
- **Use Tailwind CSS** for most styling needs as it covers common design patterns with utility classes.
- Use CSS Modules for component-specific styles when Tailwind utilities aren't sufficient.
- Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`.
- Extract shared styles into shared components to avoid duplicate imports.
- Turn off linters or formatters that auto-sort imports like ESLint’s [`sort-imports`](https://eslint.org/docs/latest/rules/sort-imports).
......
......@@ -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/getting-started/css#css-modules)
- [Tailwind CSS](/docs/app/guides/tailwind-css)
- [Tailwind CSS](/docs/app/getting-started/css#tailwind-css)
- [Global Styles](/docs/app/getting-started/css#global-css)
- [CSS-in-JS](/docs/app/guides/css-in-js)
- [External Stylesheets](/docs/app/getting-started/css#external-stylesheets)
......@@ -921,7 +921,7 @@ export default function RootLayout({ children }) {
}
```
Learn more about [styling with Tailwind CSS](/docs/app/guides/tailwind-css)
Learn more about [styling with Tailwind CSS](/docs/app/getting-started/css#tailwind-css)
## Using App Router together with Pages Router
......
......@@ -300,7 +300,7 @@ export default function RootLayout({
}
```
If you’re using Tailwind CSS, see our [installation docs](/docs/app/guides/tailwind-css).
If you're using Tailwind CSS, see our [installation docs](/docs/app/getting-started/css#tailwind-css).
### Step 6: Create the Entrypoint Page
......
---
title: How to install Tailwind CSS in your Next.js application
nav_title: Tailwind CSS
description: Style your Next.js Application using Tailwind CSS.
title: How to install Tailwind CSS v3 in your Next.js application
nav_title: Tailwind CSS v3
description: Style your Next.js Application using Tailwind CSS v3 for broader browser support.
---
{/* 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. This guide will walk you through how to install Tailwind CSS in your Next.js application.
This guide will walk you through how to install [Tailwind CSS v3](https://v3.tailwindcss.com/) in your Next.js application.
## Installing Tailwind
> **Good to know:** For the latest Tailwind 4 setup, see the [Tailwind CSS setup instructions](/docs/app/getting-started/css#tailwind-css).
Install the necessary Tailwind CSS packages:
## Installing Tailwind v3
```bash filename="Terminal"
npm install -D tailwindcss @tailwindcss/postcss postcss
```
Install Tailwind CSS and its peer dependencies, then run the `init` command to generate both `tailwind.config.js` and `postcss.config.js` files:
> **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.
```bash package="pnpm"
pnpm add -D tailwindcss@^3 postcss autoprefixer
npx tailwindcss init -p
```
## Configuring Tailwind
```bash package="npm"
npm install -D tailwindcss@^3 postcss autoprefixer
npx tailwindcss init -p
```
Create a `postcss.config.mjs` file in the root of your project and add the `@tailwindcss/postcss` plugin to your PostCSS configuration:
```bash package="yarn"
yarn add -D tailwindcss@^3 postcss autoprefixer
npx tailwindcss init -p
```
```js filename="postcss.config.mjs" highlight={3}
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}
```bash package="bun"
bun add -D tailwindcss@^3 postcss autoprefixer
bunx tailwindcss init -p
```
As of [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4), there is zero configuration required by default. If you do need to configure Tailwind, you can follow the [official documentation](https://tailwindcss.com/blog/tailwindcss-v4#css-first-configuration) for configuring the global CSS file.
## Configuring Tailwind v3
There is also an [upgrade CLI](https://tailwindcss.com/docs/upgrade-guide) and [guide](https://tailwindcss.com/docs/upgrade-guide) if you have an existing Tailwind v3 project.
Configure your template paths in your `tailwind.config.js` file:
<AppOnly>
## Importing Styles
```js filename="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
'./app/**/*.{js,ts,jsx,tsx,mdx}',
'./pages/**/*.{js,ts,jsx,tsx,mdx}',
'./components/**/*.{js,ts,jsx,tsx,mdx}',
],
theme: {
extend: {},
},
plugins: [],
}
```
Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/app/getting-started/css#global-css) in your application, for example:
Add the Tailwind directives to your global CSS file:
```css filename="app/globals.css"
@import 'tailwindcss';
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Inside the [root layout](/docs/app/api-reference/file-conventions/layout#root-layout) (`app/layout.tsx`), import the `globals.css` stylesheet to apply the styles to every route in your application.
Import the CSS file in your root layout:
```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,
}: {
......@@ -71,14 +82,8 @@ export default function RootLayout({
```
```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">
......@@ -88,58 +93,66 @@ export default function RootLayout({ children }) {
}
```
## Using Classes
After installing Tailwind CSS and adding the global styles, you can use 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>
}
```
</AppOnly>
<PagesOnly>
## Importing Styles
```js filename="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
'./pages/**/*.{js,ts,jsx,tsx,mdx}',
'./components/**/*.{js,ts,jsx,tsx,mdx}',
'./app/**/*.{js,ts,jsx,tsx,mdx}',
],
theme: {
extend: {},
},
plugins: [],
}
```
Add the [Tailwind CSS directives](https://tailwindcss.com/docs/functions-and-directives#directives) that Tailwind will use to inject its generated styles to a [Global Stylesheet](/docs/app/getting-started/css#global-css) in your application, for example:
Add the Tailwind directives to your global CSS file:
```css filename="styles/globals.css"
@import 'tailwindcss';
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Inside the [custom app file](/docs/pages/building-your-application/routing/custom-app) (`pages/_app.js`), import the `globals.css` stylesheet to apply the styles to every route in your application.
Import the CSS file in your `pages/_app.js` file:
```tsx filename="pages/_app.tsx" switcher
// These styles apply to every route in the application
```jsx filename="pages/_app.js"
import '@/styles/globals.css'
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
export default function MyApp({ Component, pageProps }) {
return <Component {...pageProps} />
}
```
```jsx filename="pages/_app.js" switcher
// These styles apply to every route in the application
import '@/styles/globals.css'
</PagesOnly>
export default function App({ Component, pageProps }) {
return <Component {...pageProps} />
## Using classes
After installing Tailwind CSS and adding the global styles, you can use Tailwind's utility classes in your application.
<AppOnly>
```tsx filename="app/page.tsx" switcher
export default function Page() {
return <h1 className="text-3xl font-bold underline">Hello, Next.js!</h1>
}
```
## Using Classes
```jsx filename="app/page.js" switcher
export default function Page() {
return <h1 className="text-3xl font-bold underline">Hello, Next.js!</h1>
}
```
After installing Tailwind CSS and adding the global styles, you can use Tailwind's utility classes in your application.
</AppOnly>
<PagesOnly>
```tsx filename="pages/index.tsx" switcher
export default function Page() {
......
......@@ -827,11 +827,7 @@ export default function MyApp({ Component, pageProps }) {
</PagesOnly>
Finally, add the CSS variable to your [Tailwind CSS config](/docs/app/guides/tailwind-css#configuring-tailwind):
### Tailwind CSS v4
As of [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4), there is zero configuration required by default. If you do need to configure Tailwind, you can follow the [official documentation](https://tailwindcss.com/blog/tailwindcss-v4#css-first-configuration) for configuring the global CSS file.
Finally, add the CSS variable to your [Tailwind CSS config](/docs/app/getting-started/css#tailwind-css):
```css filename="global.css"
@import 'tailwindcss';
......
......@@ -6,7 +6,7 @@ related:
title: Next Steps
description: Learn more about the features mentioned in this page.
links:
- pages/guides/tailwind-css
- pages/guides/tailwind-v3-css
- pages/guides/sass
- pages/guides/css-in-js
source: app/getting-started/css
......
---
title: Tailwind CSS
description: Style your Next.js Application using Tailwind CSS.
source: app/guides/tailwind-css
source: app/guides/tailwind-v3-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. */}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment