Merge branch 'canary' into update/fonts-data-1745540061055

Author: ztanner

docs/01-app/01-getting-started/01-installation.mdx

@@ -202,7 +202,7 @@ export default function Document() {
 
 ### Create the `public` folder (optional)
 
-Create a [`public` folder](/docs/app/building-your-application/optimizing/static-assets) at the root of your project to store static assets such as images, fonts, etc. Files inside `public` can then be referenced by your code starting from the base URL (`/`).
+Create a [`public` folder](/docs/app/api-reference/file-conventions/public-folder) at the root of your project to store static assets such as images, fonts, etc. Files inside `public` can then be referenced by your code starting from the base URL (`/`).
 
 You can then reference these assets using the root path (`/`). For example, `public/profile.png` can be referenced as `/profile.png`:
 

docs/01-app/01-getting-started/02-project-structure.mdx

@@ -20,12 +20,12 @@ Top-level folders are used to organize your application's code and static assets
   height="525"
 />
 
-|                                                                          |                                    |
-| ------------------------------------------------------------------------ | ---------------------------------- |
-| [`app`](/docs/app/building-your-application/routing)                     | App Router                         |
-| [`pages`](/docs/pages/building-your-application/routing)                 | Pages Router                       |
-| [`public`](/docs/app/building-your-application/optimizing/static-assets) | Static assets to be served         |
-| [`src`](/docs/app/api-reference/file-conventions/src-folder)             | Optional application source folder |
+|                                                                    |                                    |
+| ------------------------------------------------------------------ | ---------------------------------- |
+| [`app`](/docs/app/building-your-application/routing)               | App Router                         |
+| [`pages`](/docs/pages/building-your-application/routing)           | Pages Router                       |
+| [`public`](/docs/app/api-reference/file-conventions/public-folder) | Static assets to be served         |
+| [`src`](/docs/app/api-reference/file-conventions/src-folder)       | Optional application source folder |
 
 ### Top-level files
 

docs/01-app/01-getting-started/05-css.mdx

@@ -3,24 +3,22 @@ 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: API Reference
-  description: Learn more about the features mentioned in this page by reading the API Reference.
+  title: Next Steps
+  description: Learn more about the features mentioned in this page.
   links:
-    - app/api-reference/config/next-config-js/sassOptions
-    - architecture/nextjs-compiler
+    - app/guides/sass
+    - app/guides/css-in-js
 ---
 
 Next.js provides several ways to use CSS in your application, including:
 
 - [CSS Modules](#css-modules)
 - [Global CSS](#global-css)
 - [Tailwind CSS](#tailwind-css)
-- [Sass](#sass)
-- [CSS-in-JS](#css-in-js)
+- [Sass](/docs/app/guides/sass)
+- [CSS-in-JS](/docs/app/guides/css-in-js)
 - [External Stylesheets](#external-stylesheets)
 
-This page will guide you through how to use each of these approaches.
-
 ## 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.
@@ -185,292 +183,6 @@ export default function Page() {
 }
 ```
 
-## Sass
-
-Next.js integrates with [Sass](https://sass-lang.com/) using both the [`.scss`](https://sass-lang.com/documentation/syntax/#scss) and [`.sass`](https://sass-lang.com/documentation/syntax#the-indented-syntax) extensions and syntax.
-
-You can also use component-level Sass via [CSS Modules](#css-modules) and the `.module.scss`or `.module.sass` extension.
-
-### Installing Sass
-
-To start using Sass, install the `sass` package:
-
-```bash filename="Terminal"
-npm install --save-dev sass
-```
-
-### Customizing Sass options
-
-If you want to configure your Sass options, use the [`sassOptions`](/docs/app/api-reference/config/next-config-js/sassOptions) option in `next.config.js`.
-
-```ts filename="next.config.ts" switcher
-import type { NextConfig } from 'next'
-
-const nextConfig: NextConfig = {
-  sassOptions: {
-    additionalData: `$var: red;`,
-  },
-}
-
-export default nextConfig
-```
-
-```js filename="next.config.mjs" switcher
-/** @type {import('next').NextConfig} */
-
-const nextConfig = {
-  sassOptions: {
-    additionalData: `$var: red;`,
-  },
-}
-
-export default nextConfig
-```
-
-## CSS-in-JS
-
-> **Warning:** CSS-in-JS libraries which require runtime JavaScript are not currently supported in React Server Components. Using CSS-in-JS with newer React features like Server Components and Streaming requires library authors to support the latest version of React.
-
-The following libraries are supported in **Client Components** in the `app` directory (alphabetical):
-
-- [`ant-design`](https://ant.design/docs/react/use-with-next#using-app-router)
-- [`chakra-ui`](https://chakra-ui.com/docs/get-started/frameworks/next-app)
-- [`@fluentui/react-components`](https://react.fluentui.dev/?path=/docs/concepts-developer-server-side-rendering-next-js-appdir-setup--page)
-- [`kuma-ui`](https://kuma-ui.com)
-- [`@mui/material`](https://mui.com/material-ui/guides/next-js-app-router/)
-- [`@mui/joy`](https://mui.com/joy-ui/integrations/next-js-app-router/)
-- [`pandacss`](https://panda-css.com)
-- [`styled-jsx`](#styled-jsx)
-- [`styled-components`](#styled-components)
-- [`stylex`](https://stylexjs.com)
-- [`tamagui`](https://tamagui.dev/docs/guides/next-js#server-components)
-- [`tss-react`](https://tss-react.dev/)
-- [`vanilla-extract`](https://vanilla-extract.style)
-
-The following are currently working on support:
-
-- [`emotion`](https://github.com/emotion-js/emotion/issues/2928)
-
-If you want to style Server Components, we recommend using [CSS Modules](#css-modules) or other solutions that output CSS files, like [Tailwind CSS](#tailwind-css).
-
-### Configuring CSS-in-JS
-
-To configure CSS-in-JS, you need to:
-
-1. Create a **style registry** to collect all CSS rules in a render.
-2. Use the `useServerInsertedHTML` hook to inject rules before any content that might use them.
-3. Create a Client Component that wraps your app with the style registry during initial server-side rendering.
-
-#### `styled-jsx`
-
-To configure `styled-jsx` for your application, create a new registry:
-
-```tsx filename="app/registry.tsx" switcher
-'use client'
-
-import React, { useState } from 'react'
-import { useServerInsertedHTML } from 'next/navigation'
-import { StyleRegistry, createStyleRegistry } from 'styled-jsx'
-
-export default function StyledJsxRegistry({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  // Only create stylesheet once with lazy initial state
-  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
-  const [jsxStyleRegistry] = useState(() => createStyleRegistry())
-
-  useServerInsertedHTML(() => {
-    const styles = jsxStyleRegistry.styles()
-    jsxStyleRegistry.flush()
-    return <>{styles}</>
-  })
-
-  return <StyleRegistry registry={jsxStyleRegistry}>{children}</StyleRegistry>
-}
-```
-
-```jsx filename="app/registry.js" switcher
-'use client'
-
-import React, { useState } from 'react'
-import { useServerInsertedHTML } from 'next/navigation'
-import { StyleRegistry, createStyleRegistry } from 'styled-jsx'
-
-export default function StyledJsxRegistry({ children }) {
-  // Only create stylesheet once with lazy initial state
-  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
-  const [jsxStyleRegistry] = useState(() => createStyleRegistry())
-
-  useServerInsertedHTML(() => {
-    const styles = jsxStyleRegistry.styles()
-    jsxStyleRegistry.flush()
-    return <>{styles}</>
-  })
-
-  return <StyleRegistry registry={jsxStyleRegistry}>{children}</StyleRegistry>
-}
-```
-
-Then, wrap your [root layout](/docs/app/api-reference/file-conventions/layout#root-layouts) with the registry:
-
-```tsx filename="app/layout.tsx" switcher
-import StyledJsxRegistry from './registry'
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  return (
-    <html>
-      <body>
-        <StyledJsxRegistry>{children}</StyledJsxRegistry>
-      </body>
-    </html>
-  )
-}
-```
-
-```jsx filename="app/layout.js" switcher
-import StyledJsxRegistry from './registry'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <StyledJsxRegistry>{children}</StyledJsxRegistry>
-      </body>
-    </html>
-  )
-}
-```
-
-#### `styled-components`
-
-To use `styled-components`, enable it in `next.config.js`:
-
-```ts filename="next.config.ts" switcher
-import type { NextConfig } from 'next'
-
-const nextConfig: NextConfig = {
-  compiler: {
-    styledComponents: true,
-  },
-}
-
-export default nextConfig
-```
-
-```js filename="next.config.mjs" switcher
-/** @type {import('next').NextConfig} */
-
-const nextConfig = {
-  compiler: {
-    styledComponents: true,
-  },
-}
-
-export default nextConfig
-```
-
-Then, use the `styled-components` API to create a global registry component to collect all CSS style rules generated during a render, and a function to return those rules. Then use the `useServerInsertedHTML` hook to inject the styles collected in the registry into the `<head>` HTML tag in the root layout.
-
-```tsx filename="lib/registry.tsx" switcher
-'use client'
-
-import React, { useState } from 'react'
-import { useServerInsertedHTML } from 'next/navigation'
-import { ServerStyleSheet, StyleSheetManager } from 'styled-components'
-
-export default function StyledComponentsRegistry({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  // Only create stylesheet once with lazy initial state
-  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
-  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet())
-
-  useServerInsertedHTML(() => {
-    const styles = styledComponentsStyleSheet.getStyleElement()
-    styledComponentsStyleSheet.instance.clearTag()
-    return <>{styles}</>
-  })
-
-  if (typeof window !== 'undefined') return <>{children}</>
-
-  return (
-    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
-      {children}
-    </StyleSheetManager>
-  )
-}
-```
-
-```jsx filename="lib/registry.js" switcher
-'use client'
-
-import React, { useState } from 'react'
-import { useServerInsertedHTML } from 'next/navigation'
-import { ServerStyleSheet, StyleSheetManager } from 'styled-components'
-
-export default function StyledComponentsRegistry({ children }) {
-  // Only create stylesheet once with lazy initial state
-  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
-  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet())
-
-  useServerInsertedHTML(() => {
-    const styles = styledComponentsStyleSheet.getStyleElement()
-    styledComponentsStyleSheet.instance.clearTag()
-    return <>{styles}</>
-  })
-
-  if (typeof window !== 'undefined') return <>{children}</>
-
-  return (
-    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
-      {children}
-    </StyleSheetManager>
-  )
-}
-```
-
-Wrap the `children` of the root layout with the style registry component:
-
-```tsx filename="app/layout.tsx" switcher
-import StyledComponentsRegistry from './lib/registry'
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  return (
-    <html>
-      <body>
-        <StyledComponentsRegistry>{children}</StyledComponentsRegistry>
-      </body>
-    </html>
-  )
-}
-```
-
-```jsx filename="app/layout.js" switcher
-import StyledComponentsRegistry from './lib/registry'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <StyledComponentsRegistry>{children}</StyledComponentsRegistry>
-      </body>
-    </html>
-  )
-}
-```
-
 ## External stylesheets
 
 Stylesheets published by external packages can be imported anywhere in the `app` directory, including colocated components:

docs/01-app/01-getting-started/10-metadata-and-og-images.mdx

@@ -302,5 +302,5 @@ export default async function Image({ params }) {
 > **Good to know**:
 >
 > - Examples are available in the [Vercel OG Playground](https://og-playground.vercel.app/).
-> - `ImageResponse` uses [@vercel/og](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation), [Satori](https://github.com/vercel/satori), and Resvg to convert HTML and CSS into PNG.
+> - `ImageResponse` uses [`@vercel/og`](https://vercel.com/docs/og-image-generation), [`satori`](https://github.com/vercel/satori), and `resvg` to convert HTML and CSS into PNG.
 > - Only flexbox and a subset of CSS properties are supported. Advanced layouts (e.g. `display: grid`) will not work.

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

@@ -1,5 +1,6 @@
 ---
-title: CSS-in-JS
+title: How to use CSS-in-JS libraries
+nav_title: CSS-in-JS
 description: Use CSS-in-JS libraries with Next.js
 ---
 

docs/01-app/02-guides/migrating/app-router-migration.mdx

@@ -889,9 +889,9 @@ In the `pages` directory, global stylesheets are restricted to only `pages/_app.
 - [CSS Modules](/docs/app/building-your-application/styling/css#css-modules)
 - [Tailwind CSS](/docs/app/building-your-application/styling/tailwind-css)
 - [Global Styles](/docs/app/building-your-application/styling/css#global-styles)
-- [CSS-in-JS](/docs/app/building-your-application/styling/css-in-js)
+- [CSS-in-JS](/docs/app/guides/css-in-js)
 - [External Stylesheets](/docs/app/building-your-application/styling/css#external-stylesheets)
-- [Sass](/docs/app/building-your-application/styling/sass)
+- [Sass](/docs/app/guides/sass)
 
 #### Tailwind CSS