Merge branch 'canary' into 07-17-remove_the_experimental_env_var

Author: huozhi

.github/workflows/build_and_deploy.yml

@@ -9,7 +9,7 @@ on:
 
 env:
   NAPI_CLI_VERSION: 2.16.2
-  TURBO_VERSION: 2.0.6-canary.0
+  TURBO_VERSION: 2.0.7
   NODE_LTS_VERSION: 20
   CARGO_PROFILE_RELEASE_LTO: 'true'
   TURBO_TEAM: 'vercel'

.github/workflows/build_and_test.yml

@@ -8,7 +8,7 @@ on:
 
 env:
   NAPI_CLI_VERSION: 2.14.7
-  TURBO_VERSION: 2.0.6-canary.0
+  TURBO_VERSION: 2.0.7
   NODE_MAINTENANCE_VERSION: 18
   NODE_LTS_VERSION: 20
   TEST_CONCURRENCY: 8

.github/workflows/code_freeze.yml

@@ -17,7 +17,7 @@ name: Code Freeze
 
 env:
   NAPI_CLI_VERSION: 2.14.7
-  TURBO_VERSION: 2.0.6-canary.0
+  TURBO_VERSION: 2.0.7
   NODE_LTS_VERSION: 20
 
 jobs:

.github/workflows/pull_request_stats.yml

@@ -6,7 +6,7 @@ name: Generate Pull Request Stats
 
 env:
   NAPI_CLI_VERSION: 2.14.7
-  TURBO_VERSION: 2.0.6-canary.0
+  TURBO_VERSION: 2.0.7
   NODE_LTS_VERSION: 20
   TEST_CONCURRENCY: 6
 

.github/workflows/trigger_release.yml

@@ -35,7 +35,7 @@ name: Trigger Release
 
 env:
   NAPI_CLI_VERSION: 2.14.7
-  TURBO_VERSION: 2.0.6-canary.0
+  TURBO_VERSION: 2.0.7
   NODE_LTS_VERSION: 20
 
 jobs:

docs/02-app/01-building-your-application/05-styling/01-css-modules.mdx renamed to docs/02-app/01-building-your-application/05-styling/01-stylesheets.mdx

@@ -1,6 +1,6 @@
 ---
-title: CSS Modules and Global Styles
-nav_title: CSS Modules
+title: Stylesheets
+nav_title: 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.
 
 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>
 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
 <AppOnly>
 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`:
 
@@ -300,7 +303,7 @@ function ExampleDialog(props) {
 
 ## 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>`:
 
@@ -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`.
 - 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).
+- 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:**
 >

docs/02-app/01-building-your-application/05-styling/02-tailwind-css.mdx

@@ -55,7 +55,7 @@ You do not need to modify `postcss.config.js`.
 
 ## 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"
 @tailwind base;

docs/02-app/01-building-your-application/05-styling/04-css-in-js.mdx

@@ -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.
 
-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`
 

docs/02-app/01-building-your-application/05-styling/index.mdx

@@ -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:
 
-- **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.
+- **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.
 - **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.

docs/02-app/01-building-your-application/06-optimizing/01-images.mdx

@@ -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:
 
 - 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 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`