From d94466c7803f8582ca81c13baf592610e10dad7c Mon Sep 17 00:00:00 2001
From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Date: Thu, 11 Apr 2024 19:59:38 +0100
Subject: [PATCH] Docs: Add recommendations for CSS import order (#64321)

---
 .../05-styling/01-css-modules.mdx             | 71 +++++++++++++++++--
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx b/docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx
index ddcdb6c0af6b9..07493272c3770 100644
--- a/docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx
+++ b/docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx
@@ -1,6 +1,7 @@
 ---
-title: CSS Modules
-description: Style your Next.js Application with CSS Modules.
+title: CSS Modules and Global Styles
+nav_title: CSS Modules
+description: Style your Next.js Application with CSS Modules, Global Styles, and external stylesheets.
 ---
 
 {/* 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. */}
@@ -16,6 +17,14 @@ description: Style your Next.js Application with CSS Modules.
 
 </PagesOnly>
 
+Next.js supports different types of stylesheets, including:
+
+- [CSS Modules](#css-modules)
+- [Global Styles](#global-styles)
+- [External Stylesheets](#external-stylesheets)
+
+## CSS Modules
+
 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.
@@ -91,8 +100,7 @@ export function Button() {
 
 </PagesOnly>
 
-CSS Modules are an _optional feature_ and are **only enabled for files with the `.module.css` extension**.
-Regular `<link>` stylesheets and global CSS files are still supported.
+CSS Modules are **only enabled for files with the `.module.css` and `.module.sass` extensions**.
 
 In production, all CSS Module files will be automatically concatenated into **many minified and code-split** `.css` files.
 These `.css` files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded for your application to paint.
@@ -288,6 +296,61 @@ function ExampleDialog(props) {
 
 </PagesOnly>
 
+<AppOnly>
+
+## 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.
+
+For example, `base-button.module.css` will be ordered before `page.module.css` since `<BaseButton>` is imported first in `<Page>`:
+
+```tsx filename="base-button.tsx" switcher
+import styles from './base-button.module.css'
+
+export function BaseButton() {
+  return <button className={styles.primary} />
+}
+```
+
+```jsx filename="base-button.js" switcher
+import styles from './base-button.module.css'
+
+export function BaseButton() {
+  return <button className={styles.primary} />
+}
+```
+
+```tsx filename="page.ts" switcher
+import { BaseButton } from './base-button'
+import styles from './page.module.css'
+
+export function Page() {
+  return <BaseButton className={styles.primary} />
+}
+```
+
+```jsx filename="page.js" switcher
+import { BaseButton } from './base-button'
+import styles from './page.module.css'
+
+export function Page() {
+  return <BaseButton className={styles.primary} />
+}
+```
+
+To maintain a predictable order, we recommend the following:
+
+- Only import a CSS file in a single JS/TS file.
+  - If using global class names, import the global styles in the same file in the order you want them to be applied.
+- 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/pages-and-layouts#root-layout-required).
+
+> **Good to know:** CSS ordering behaves differently in development mode, always ensure to check preview deployments to verify the final CSS order in your production build.
+
+</AppOnly>
+
 ## Additional Features
 
 Next.js includes additional features to improve the authoring experience of adding styles: