Unverified Commit 01cdb26d authored by Sam Ko's avatar Sam Ko Committed by GitHub

docs: add important info around global styles (#67778)

## Why?

- We currently don't document why we don't remove styles on navigation.
This was true with Pages Router, but it wasn't necessarily an issue
folks reported on because we reinforced global css to only be available
in `_app.js`. With App Router, we need to be explicit as to why this is
the case.
- We currently don't recommend turning off sort-imports from
linters/formatters since CSS import order matters.

x-ref:
https://github.com/vercel/next.js/issues/58597#issuecomment-2226512480,
https://github.com/vercel/next.js/issues/58597

---------
Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
parent d33d57d6
--- ---
title: CSS Modules and Global Styles title: Stylesheets
nav_title: CSS Modules nav_title: Stylesheets
description: Style your Next.js Application with CSS Modules, Global Styles, and external stylesheets. description: Style your Next.js Application with CSS Modules, Global Styles, and external stylesheets.
--- ---
...@@ -29,7 +29,7 @@ Next.js has built-in support for CSS Modules using the `.module.css` extension. ...@@ -29,7 +29,7 @@ Next.js has built-in support for CSS Modules using the `.module.css` extension.
CSS Modules locally scope CSS by automatically creating a unique class name. This allows you to use the same class name in different files without worrying about collisions. This behavior makes CSS Modules the ideal way to include component-level CSS. CSS Modules locally scope CSS by automatically creating a unique class name. This allows you to use the same class name in different files without worrying about collisions. This behavior makes CSS Modules the ideal way to include component-level CSS.
## Example ### Example
<AppOnly> <AppOnly>
CSS Modules can be imported into any file inside the `app` directory: CSS Modules can be imported into any file inside the `app` directory:
...@@ -110,7 +110,10 @@ These `.css` files represent hot execution paths in your application, ensuring t ...@@ -110,7 +110,10 @@ These `.css` files represent hot execution paths in your application, ensuring t
<AppOnly> <AppOnly>
Global styles can be imported into any layout, page, or component inside the `app` directory. Global styles can be imported into any layout, page, or component inside the `app` directory.
> **Good to know**: This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file. > **Good to know**:
>
> - This is different from the `pages` directory, where you can only import global styles inside the `_app.js` file.
> - Next.js does not support usage of global styles unless they are actually global, meaning they can apply to all pages and can live for the lifetime of the application. This is because Next.js uses React's built-in support for stylesheets to integrate with Suspense. This built-in support currently does not remove stylesheets as you navigate between routes. Because of this, we recommend using CSS Modules over global styles.
For example, consider a stylesheet named `app/global.css`: For example, consider a stylesheet named `app/global.css`:
...@@ -300,7 +303,7 @@ function ExampleDialog(props) { ...@@ -300,7 +303,7 @@ function ExampleDialog(props) {
## Ordering and Merging ## Ordering and Merging
Next.js optimizes CSS during production builds by automatically chunking (merging) stylesheets. The CSS order is determined by the order in which you import the stylesheets into your application code. Next.js optimizes CSS during production builds by automatically chunking (merging) stylesheets. The CSS order is _determined by the order in which you import the stylesheets into your application code_.
For example, `base-button.module.css` will be ordered before `page.module.css` since `<BaseButton>` is imported first in `<Page>`: For example, `base-button.module.css` will be ordered before `page.module.css` since `<BaseButton>` is imported first in `<Page>`:
...@@ -346,6 +349,7 @@ To maintain a predictable order, we recommend the following: ...@@ -346,6 +349,7 @@ To maintain a predictable order, we recommend the following:
- Use a consistent naming convention for your CSS modules. For example, using `<name>.module.css` over `<name>.tsx`. - 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. - 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/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).
- 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:** > **Good to know:**
> >
......
...@@ -55,7 +55,7 @@ You do not need to modify `postcss.config.js`. ...@@ -55,7 +55,7 @@ You do not need to modify `postcss.config.js`.
## Importing Styles ## Importing Styles
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/building-your-application/styling/css-modules#global-styles) in your application, for example: 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/building-your-application/styling/stylesheets#global-styles) in your application, for example:
```css filename="app/globals.css" ```css filename="app/globals.css"
@tailwind base; @tailwind base;
......
...@@ -33,7 +33,7 @@ The following are currently working on support: ...@@ -33,7 +33,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. > **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-modules) 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/stylesheets) or other solutions that output CSS files, like PostCSS or [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css).
## Configuring CSS-in-JS in `app` ## Configuring CSS-in-JS in `app`
......
...@@ -7,8 +7,8 @@ description: Learn the different ways you can style your Next.js application. ...@@ -7,8 +7,8 @@ description: Learn the different ways you can style your Next.js application.
Next.js supports different ways of styling your application, including: Next.js supports different ways of styling your application, including:
- **Global CSS**: Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.
- **CSS Modules**: Create locally scoped CSS classes to avoid naming conflicts and improve maintainability. - **CSS Modules**: Create locally scoped CSS classes to avoid naming conflicts and improve maintainability.
- **Global CSS**: Simple to use and familiar for those experienced with traditional CSS, but can lead to larger CSS bundles and difficulty managing styles as the application grows.
- **Tailwind CSS**: A utility-first CSS framework that allows for rapid custom designs by composing utility classes. - **Tailwind CSS**: A utility-first CSS framework that allows for rapid custom designs by composing utility classes.
- **Sass**: A popular CSS preprocessor that extends CSS with features like variables, nested rules, and mixins. - **Sass**: A popular CSS preprocessor that extends CSS with features like variables, nested rules, and mixins.
- **CSS-in-JS**: Embed CSS directly in your JavaScript components, enabling dynamic and scoped styling. - **CSS-in-JS**: Embed CSS directly in your JavaScript components, enabling dynamic and scoped styling.
......
...@@ -229,7 +229,7 @@ If none of the suggested methods works for sizing your images, the `next/image` ...@@ -229,7 +229,7 @@ If none of the suggested methods works for sizing your images, the `next/image`
Styling the Image component is similar to styling a normal `<img>` element, but there are a few guidelines to keep in mind: Styling the Image component is similar to styling a normal `<img>` element, but there are a few guidelines to keep in mind:
- Use `className` or `style`, not `styled-jsx`. - Use `className` or `style`, not `styled-jsx`.
- In most cases, we recommend using the `className` prop. This can be an imported [CSS Module](/docs/app/building-your-application/styling/css-modules), a [global stylesheet](/docs/app/building-your-application/styling/css-modules#global-styles), etc. - In most cases, we recommend using the `className` prop. This can be an imported [CSS Module](/docs/app/building-your-application/styling/stylesheets), a [global stylesheet](/docs/app/building-your-application/styling/stylesheets#global-styles), etc.
- You can also use the `style` prop to assign inline styles. - You can also use the `style` prop to assign inline styles.
- You cannot use [styled-jsx](/docs/app/building-your-application/styling/css-in-js) because it's scoped to the current component (unless you mark the style as `global`). - You cannot use [styled-jsx](/docs/app/building-your-application/styling/css-in-js) because it's scoped to the current component (unless you mark the style as `global`).
- When using `fill`, the parent element must have `position: relative` - When using `fill`, the parent element must have `position: relative`
......
...@@ -876,11 +876,11 @@ export async function GET(request) {} ...@@ -876,11 +876,11 @@ export async function GET(request) {}
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. 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-modules) - [CSS Modules](/docs/app/building-your-application/styling/stylesheets)
- [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css) - [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css)
- [Global Styles](/docs/app/building-your-application/styling/css-modules#global-styles) - [Global Styles](/docs/app/building-your-application/styling/stylesheets#global-styles)
- [CSS-in-JS](/docs/app/building-your-application/styling/css-in-js) - [CSS-in-JS](/docs/app/building-your-application/styling/css-in-js)
- [External Stylesheets](/docs/app/building-your-application/styling/css-modules#external-stylesheets) - [External Stylesheets](/docs/app/building-your-application/styling/stylesheets#external-stylesheets)
- [Sass](/docs/app/building-your-application/styling/sass) - [Sass](/docs/app/building-your-application/styling/sass)
#### Tailwind CSS #### Tailwind CSS
......
...@@ -313,7 +313,7 @@ With the above changes, you shifted from declaring everything in your `index.htm ...@@ -313,7 +313,7 @@ With the above changes, you shifted from declaring everything in your `index.htm
### Step 6: Styles ### Step 6: Styles
Like Create React App, Next.js has built-in support for [CSS Modules](/docs/app/building-your-application/styling/css-modules). Like Create React App, Next.js has built-in support for [CSS Modules](/docs/app/building-your-application/styling/stylesheets).
If you're using a global CSS file, import it into your `app/layout.tsx` file: If you're using a global CSS file, import it into your `app/layout.tsx` file:
......
...@@ -1017,7 +1017,7 @@ The following metadata types do not currently have built-in support. However, th ...@@ -1017,7 +1017,7 @@ The following metadata types do not currently have built-in support. However, th
| `<meta http-equiv="...">` | Use appropriate HTTP Headers via [`redirect()`](/docs/app/api-reference/functions/redirect), [Middleware](/docs/app/building-your-application/routing/middleware#nextresponse), [Security Headers](/docs/app/api-reference/next-config-js/headers) | | `<meta http-equiv="...">` | Use appropriate HTTP Headers via [`redirect()`](/docs/app/api-reference/functions/redirect), [Middleware](/docs/app/building-your-application/routing/middleware#nextresponse), [Security Headers](/docs/app/api-reference/next-config-js/headers) |
| `<base>` | Render the tag in the layout or page itself. | | `<base>` | Render the tag in the layout or page itself. |
| `<noscript>` | Render the tag in the layout or page itself. | | `<noscript>` | Render the tag in the layout or page itself. |
| `<style>` | Learn more about [styling in Next.js](/docs/app/building-your-application/styling/css-modules). | | `<style>` | Learn more about [styling in Next.js](/docs/app/building-your-application/styling/stylesheets). |
| `<script>` | Learn more about [using scripts](/docs/app/building-your-application/optimizing/scripts). | | `<script>` | Learn more about [using scripts](/docs/app/building-your-application/optimizing/scripts). |
| `<link rel="stylesheet" />` | `import` stylesheets directly in the layout or page itself. | | `<link rel="stylesheet" />` | `import` stylesheets directly in the layout or page itself. |
| `<link rel="preload />` | Use [ReactDOM preload method](#link-relpreload) | | `<link rel="preload />` | Use [ReactDOM preload method](#link-relpreload) |
......
...@@ -13,7 +13,7 @@ Before continuing to add custom webpack configuration to your application make s ...@@ -13,7 +13,7 @@ Before continuing to add custom webpack configuration to your application make s
<AppOnly> <AppOnly>
- [CSS imports](/docs/app/building-your-application/styling) - [CSS imports](/docs/app/building-your-application/styling)
- [CSS modules](/docs/app/building-your-application/styling/css-modules) - [CSS modules](/docs/app/building-your-application/styling/stylesheets)
- [Sass/SCSS imports](/docs/app/building-your-application/styling/sass) - [Sass/SCSS imports](/docs/app/building-your-application/styling/sass)
- [Sass/SCSS modules](/docs/app/building-your-application/styling/sass) - [Sass/SCSS modules](/docs/app/building-your-application/styling/sass)
......
--- ---
title: CSS Modules title: CSS Modules
description: Style your Next.js Application using CSS Modules. description: Style your Next.js Application using CSS Modules.
source: app/building-your-application/styling/css-modules source: app/building-your-application/styling/stylesheets
--- ---
{/* 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. */} {/* 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