Unverified Commit 354b255d authored by Delba de Oliveira's avatar Delba de Oliveira Committed by GitHub

docs: Move Sass and CSS-in-JS pages to guides (#78536)

parent 7ff78d1b
...@@ -3,11 +3,11 @@ title: How to use CSS in your application ...@@ -3,11 +3,11 @@ title: How to use CSS in your application
nav_title: CSS nav_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 CSS Modules, Global CSS, Tailwind CSS, and more.
related: related:
title: API Reference title: Next Steps
description: Learn more about the features mentioned in this page by reading the API Reference. description: Learn more about the features mentioned in this page.
links: links:
- app/api-reference/config/next-config-js/sassOptions - app/guides/sass
- architecture/nextjs-compiler - app/guides/css-in-js
--- ---
Next.js provides several ways to use CSS in your application, including: Next.js provides several ways to use CSS in your application, including:
...@@ -15,12 +15,10 @@ Next.js provides several ways to use CSS in your application, including: ...@@ -15,12 +15,10 @@ Next.js provides several ways to use CSS in your application, including:
- [CSS Modules](#css-modules) - [CSS Modules](#css-modules)
- [Global CSS](#global-css) - [Global CSS](#global-css)
- [Tailwind CSS](#tailwind-css) - [Tailwind CSS](#tailwind-css)
- [Sass](#sass) - [Sass](/docs/app/guides/sass)
- [CSS-in-JS](#css-in-js) - [CSS-in-JS](/docs/app/guides/css-in-js)
- [External Stylesheets](#external-stylesheets) - [External Stylesheets](#external-stylesheets)
This page will guide you through how to use each of these approaches.
## CSS Modules ## 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. 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() { ...@@ -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 ## External stylesheets
Stylesheets published by external packages can be imported anywhere in the `app` directory, including colocated components: Stylesheets published by external packages can be imported anywhere in the `app` directory, including colocated components:
......
--- ---
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 description: Use CSS-in-JS libraries with Next.js
--- ---
......
...@@ -889,9 +889,9 @@ In the `pages` directory, global stylesheets are restricted to only `pages/_app. ...@@ -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) - [CSS Modules](/docs/app/building-your-application/styling/css#css-modules)
- [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#global-styles) - [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) - [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 #### Tailwind CSS
......
--- ---
title: Sass title: How to use Sass
nav_title: Sass
description: Style your Next.js application using Sass. description: Style your Next.js application using Sass.
--- ---
......
...@@ -247,7 +247,7 @@ Styling the Image component is similar to styling a normal `<img>` element, but ...@@ -247,7 +247,7 @@ Styling the Image component is similar to styling a normal `<img>` element, but
- 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), a [global stylesheet](/docs/app/building-your-application/styling/css#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/css), a [global stylesheet](/docs/app/building-your-application/styling/css#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/guides/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`
- This is necessary for the proper rendering of the image element in that layout mode. - This is necessary for the proper rendering of the image element in that layout mode.
- When using `fill`, the parent element must have `display: block` - When using `fill`, the parent element must have `display: block`
......
...@@ -14,8 +14,8 @@ Before continuing to add custom webpack configuration to your application make s ...@@ -14,8 +14,8 @@ Before continuing to add custom webpack configuration to your application make s
- [CSS imports](/docs/app/building-your-application/styling/css) - [CSS imports](/docs/app/building-your-application/styling/css)
- [CSS modules](/docs/app/building-your-application/styling/css#css-modules) - [CSS modules](/docs/app/building-your-application/styling/css#css-modules)
- [Sass/SCSS imports](/docs/app/building-your-application/styling/sass) - [Sass/SCSS imports](/docs/app/guides/sass)
- [Sass/SCSS modules](/docs/app/building-your-application/styling/sass) - [Sass/SCSS modules](/docs/app/guides/sass)
</AppOnly> </AppOnly>
...@@ -23,8 +23,8 @@ Before continuing to add custom webpack configuration to your application make s ...@@ -23,8 +23,8 @@ Before continuing to add custom webpack configuration to your application make s
- [CSS imports](/docs/pages/building-your-application/styling) - [CSS imports](/docs/pages/building-your-application/styling)
- [CSS modules](/docs/pages/building-your-application/styling/css) - [CSS modules](/docs/pages/building-your-application/styling/css)
- [Sass/SCSS imports](/docs/pages/building-your-application/styling/sass) - [Sass/SCSS imports](/docs/pages/guides/sass)
- [Sass/SCSS modules](/docs/pages/building-your-application/styling/sass) - [Sass/SCSS modules](/docs/pages/guides/sass)
- [Customizing babel configuration](/docs/pages/guides/babel) - [Customizing babel configuration](/docs/pages/guides/babel)
</PagesOnly> </PagesOnly>
......
--- ---
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 description: Use CSS-in-JS libraries with Next.js
source: app/building-your-application/styling/css-in-js source: app/guides/css-in-js
--- ---
{/* 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. */}
--- ---
title: Sass title: How to use Sass in Next.js
nav_title: Sass
description: Learn how to use Sass in your Next.js application. description: Learn how to use Sass in your Next.js application.
source: app/building-your-application/styling/sass source: app/guides/sass
--- ---
{/* 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. */}
...@@ -4,7 +4,7 @@ title: 'Install `sass` to Use Built-In Sass Support' ...@@ -4,7 +4,7 @@ title: 'Install `sass` to Use Built-In Sass Support'
## Why This Error Occurred ## Why This Error Occurred
Using Next.js' [built-in Sass support](/docs/pages/building-your-application/styling/sass) requires that you bring your own version of Sass. Using Next.js' [built-in Sass support](/docs/pages/guides/sass) requires that you bring your own version of Sass.
## Possible Ways to Fix It ## Possible Ways to Fix It
...@@ -18,4 +18,4 @@ yarn add sass ...@@ -18,4 +18,4 @@ yarn add sass
## Useful Links ## Useful Links
- [Sass Support in Documentation](/docs/pages/building-your-application/styling/sass) - [Sass Support in Documentation](/docs/pages/guides/sass)
...@@ -27,5 +27,5 @@ Please see the links for more examples. ...@@ -27,5 +27,5 @@ Please see the links for more examples.
## Useful Links ## Useful Links
- [Built-In CSS-in-JS](/docs/pages/building-your-application/styling/css-in-js) - [Built-In CSS-in-JS](/docs/pages/guides/css-in-js)
- [styled-jsx documentation](https://github.com/vercel/styled-jsx) - [styled-jsx documentation](https://github.com/vercel/styled-jsx)
...@@ -52,5 +52,5 @@ const Component = () => ( ...@@ -52,5 +52,5 @@ const Component = () => (
## Useful Links ## Useful Links
- [Built-In CSS-in-JS](/docs/pages/building-your-application/styling/css-in-js) - [Built-In CSS-in-JS](/docs/pages/guides/css-in-js)
- [styled-jsx documentation](https://github.com/vercel/styled-jsx) - [styled-jsx documentation](https://github.com/vercel/styled-jsx)
...@@ -21,7 +21,7 @@ Hydration errors can occur from: ...@@ -21,7 +21,7 @@ Hydration errors can occur from:
3. Using browser-only APIs like `window` or `localStorage` in your rendering logic 3. Using browser-only APIs like `window` or `localStorage` in your rendering logic
4. Using time-dependent APIs such as the `Date()` constructor in your rendering logic 4. Using time-dependent APIs such as the `Date()` constructor in your rendering logic
5. [Browser extensions](https://github.com/facebook/react/issues/24430) modifying the HTML 5. [Browser extensions](https://github.com/facebook/react/issues/24430) modifying the HTML
6. Incorrectly configured [CSS-in-JS libraries](/docs/app/building-your-application/styling/css-in-js) 6. Incorrectly configured [CSS-in-JS libraries](/docs/app/guides/css-in-js)
1. Ensure your code is following [our official examples](https://github.com/vercel/next.js/tree/canary/examples) 1. Ensure your code is following [our official examples](https://github.com/vercel/next.js/tree/canary/examples)
7. Incorrectly configured Edge/CDN that attempts to modify the html response, such as Cloudflare [Auto Minify](https://developers.cloudflare.com/speed/optimization/content/troubleshooting/disable-auto-minify/) 7. Incorrectly configured Edge/CDN that attempts to modify the html response, such as Cloudflare [Auto Minify](https://developers.cloudflare.com/speed/optimization/content/troubleshooting/disable-auto-minify/)
......
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