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
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:
......@@ -15,12 +15,10 @@ 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:
......
---
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
---
......
......@@ -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
......
---
title: Sass
title: How to use Sass
nav_title: 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
- 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.
- 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`
- 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`
......
......@@ -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 modules](/docs/app/building-your-application/styling/css#css-modules)
- [Sass/SCSS imports](/docs/app/building-your-application/styling/sass)
- [Sass/SCSS modules](/docs/app/building-your-application/styling/sass)
- [Sass/SCSS imports](/docs/app/guides/sass)
- [Sass/SCSS modules](/docs/app/guides/sass)
</AppOnly>
......@@ -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 modules](/docs/pages/building-your-application/styling/css)
- [Sass/SCSS imports](/docs/pages/building-your-application/styling/sass)
- [Sass/SCSS modules](/docs/pages/building-your-application/styling/sass)
- [Sass/SCSS imports](/docs/pages/guides/sass)
- [Sass/SCSS modules](/docs/pages/guides/sass)
- [Customizing babel configuration](/docs/pages/guides/babel)
</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
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. */}
---
title: Sass
title: How to use Sass in Next.js
nav_title: Sass
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. */}
......@@ -4,7 +4,7 @@ title: 'Install `sass` to Use Built-In Sass Support'
## 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
......@@ -18,4 +18,4 @@ yarn add sass
## 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.
## 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)
......@@ -52,5 +52,5 @@ const Component = () => (
## 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)
......@@ -21,7 +21,7 @@ Hydration errors can occur from:
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
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)
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