forked from vercel/next.js
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs: Document
cssChunking
option (vercel#67691)
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
1 parent
761b60e
commit b7f9f1f
Showing
2 changed files
with
44 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
40 changes: 40 additions & 0 deletions
40
docs/02-app/02-api-reference/05-next-config-js/cssChunking.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |