Skip to content

Commit

Permalink
Docs: Document cssChunking option (vercel#67691)
Browse files Browse the repository at this point in the history
Closes:
[NDX-13](https://linear.app/vercel/issue/NDX-13/csschunking-config-flag)
Related:
[NDX-1](https://linear.app/vercel/issue/NDX-1/css-issues-with-app-router)

---------

Co-authored-by: Tobias Koppers <tobias.koppers@googlemail.com>
  • Loading branch information
delbaoliveira and sokra committed Jul 15, 2024
1 parent 761b60e commit b7f9f1f
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 1 deletion.
Original file line number Diff line number Diff line change
Expand Up @@ -347,7 +347,10 @@ To maintain a predictable order, we recommend the following:
- 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).

> **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.
> **Good to know:**
>
> - CSS ordering can behave differently in development mode, always ensure to check the build (`next build`) to verify the final CSS order.
> - You can use the [`cssChunking`](/docs/app/api-reference/next-config-js/cssChunking) option in `next.config.js` to control how CSS is chunked.
</AppOnly>

Expand Down
40 changes: 40 additions & 0 deletions docs/02-app/02-api-reference/05-next-config-js/cssChunking.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: cssChunking (Experimental)
description: Use the `cssChunking` option to control how CSS files are chunked in your Next.js application.
---

CSS Chunking is a strategy used to improve the performance of your web application by splitting and re-ordering CSS files into chunks. This allows you to load only the CSS that is needed for a specific route, instead of loading all the application's CSS at once.

You can control how CSS files are chunked using the `experimental.cssChunking` option in your `next.config.js` file:

```tsx filename="next.config.ts" switcher
import type { NextConfig } from 'next'

const nextConfig = {
experimental: {
cssChunking: 'loose', // default
},
} satisfies NextConfig

export default nextConfig
```

```js filename="next.config.js" switcher
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
cssChunking: 'loose', // default
},
}

module.exports = nextConfig
```

## Options

- **`'loose'` (default)**: Next.js will try to merge CSS files whenever possible, determining explicit and implicit dependencies between files from import order to reduce the number of chunks and therefore the number of requests.
- **`'strict'`**: Next.js will load CSS files in the correct order they are imported into your files, which can lead to more chunks and requests.

You may consider using `'strict'` if you run into unexpected CSS behavior. For example, if you import `a.css` and `b.css` in different files using a different `import` order (`a` before `b`, or `b` before `a`), `'loose'` will merge the files in any other and assume there are no dependencies between them. However, if `b.css` depends on `a.css`, you may want to use `'strict'` to prevent the files from being merged, and instead, load them in the order they are imported - which can result in more chunks and requests.

For most applications, we recommend `'loose'` as it leads to fewer requests and better performance.

0 comments on commit b7f9f1f

Please sign in to comment.